AI Mayak
Start

Library · Skills: teach the agent your way of working

Skill architecture (a skill is a reusable instruction for Claude): 2 archetypes

Builder55 minUpdated: October 2026
31 of 105 in the library

Module: Skills: reusable expertise | Time: about 25 min theory + 30 min practice

The gist

There are two kinds of valuable skills: ones that teach the model something new (for example, design rules it was never trained on), and ones that encode your personal way of working (which the model can't know by definition). The first kind can go stale, because models keep getting updated. The second kind never does: it's your unique expertise, and it doesn't exist anywhere else.

Key concepts

  • Capability Uplift Skills: extend what the model can do, but risk going stale
  • Encoded Preference Skills: encode a personal or business process, long-term value
  • Where skills live: global vs project level
  • Skill size: under 500 lines, big data goes into reference files
  • Subagents (a subagent is a child agent) inside skills for heavy work

Theory

Type 1: Capability Uplift Skills

🎨 Picture this: Capability Uplift is like a cheat sheet for a new hire. Claude is smart but doesn't know your niche. The skill says: "here's how real estate works in Ecuador, here are 7 rules." Smart employee + cheat sheet = does it right from day one.

What it is: skills that give the model knowledge or abilities it doesn't have by default.

Examples:

  • "Front-end design guidelines for high-converting landing pages"
  • "Data visualization best practices based on Tufte's book"
  • "Rules for drafting legal documents in Ecuador"
  • "Security standards for fintech products (PCI DSS)"

Why they work: Claude knows general design principles but not the specifics of your niche or a particular methodology. The skill fills that gap.

Risk of going stale:

Claude keeps getting updated. Each new generation of models is trained on more data and knows more: as of October 2026 the current ones are Opus 5.5 and Sonnet 5.5, and the up-to-date list lives on the What's current page. A "front-end design guidelines" skill written today may be unnecessary a year from now, because the model will have learned it on its own.

How to check whether it's still relevant:

Type this into the chat
Every 3-6 months, test it: ask the model to do the task WITHOUT the skill.
If the result is just as good, the skill is outdated and you can delete it.

When to build a Capability Uplift skill:

  • Rules specific to your niche (real estate, medicine, law)
  • Local standards (a specific country's laws, a local market)
  • Proprietary methodologies (your internal scoring system)
  • Current information (competitors, prices: things that change)

Type 2: Encoded Preference Skills

What it is: skills that encode your personal style, preferences and business processes.

Examples:

  • "My way of making infographics: data into a table first, then 3 visualization options, then pick one"
  • "Our new client onboarding process: steps 1-7 with specific questions"
  • "How I write emails to cold leads: structure, tone, length, call to action"
  • "The brand voice of a real estate agency: a restrained expert observer, no hype"

Why they don't go stale:

The model will never learn exactly how you want to work, because those are your preferences. Even the smartest model can't guess:

  • Which report format you like
  • Which questions you ask clients at the first meeting
  • What tone your brand has
  • How you prioritize your product backlog

This is your unique encoded expertise. A competitor can't copy it. The model can't invent it. Only you know it.

The most valuable in the long run: Encoded Preference Skills are what build a moat around your business. The more of these skills you have, the harder it is for competitors to reproduce your processes.

🎨 Picture this: Encoded Preference Skills are the recipe for a signature sauce that a competitor will never reproduce exactly. Even if they see the ingredients, they don't know the proportions, the temperature or the order. It's your DNA in a file.

Where to store skills: global vs project

Global folder (~/.claude/skills/):

Code
Available from ANY project
├── code-review-standards/SKILL.md   ← the same for every project
├── email-writing-style/SKILL.md     ← my style is the same everywhere
└── data-analysis-approach/SKILL.md  ← my approach to analysis

Each skill is a folder, and the main file inside is called SKILL.md.

Use it for: universal skills, personal preferences, standards that apply everywhere.

Project folder (.claude/skills/):

Code
Available ONLY in this project
├── acme-realty-brand-voice/SKILL.md   ← specific to this brand
├── ecuador-real-estate-rules/SKILL.md ← specific to this market
└── client-report-format/SKILL.md      ← the format for this client

Use it for: brand-specific skills, client processes, market specifics.

Rule of thumb: ask yourself "does this skill belong only in this project, or everywhere?" → project or global.

Skill size: the 500-line rule

The problem with big skills:

The bigger the skill, the more tokens (a token is a unit of text for AI) it takes to load. A 2,000-line skill means every request that uses it = 2,000 lines of context (context is the text the AI can see). That's expensive and slow.

🎨 Picture this: a big skill is like a backpack stuffed with everything that might come in handy on a hike. It weighs 65 pounds. You carry it all the time, even when you're just going out for bread. The 500-line rule is a day pack: only what you need today.

The rule: keep a skill under 500 lines (roughly 5-10 KB). This is a recommendation from the Claude Code documentation.

What to move into reference files:

Code
# Don't cram into SKILL.md:
# - The full list of 500 competitors
# - All pricing data (it changes)
# - Big templates (HTML/CSS)
# - Libraries of content examples

# Instead, separate files in the skill folder that SKILL.md points to:
my-skill/
  SKILL.md
  data/competitors-database.json   # big JSON
  templates/report-layout.html     # HTML template
  brand/content-examples/          # folder with examples

In the text of SKILL.md you say when to open which file. The skill reads a file only when it's needed: if the task doesn't call for competitive analysis, competitors-database.json doesn't get loaded.

Inline context vs reference files

Inline (right in the body of the skill):

  • Critical rules that always apply
  • The structure of the process
  • Parameters and settings

Reference files:

  • Bulky data (lists, tables)
  • Templates (HTML, Excel)
  • Data that changes (prices, competitors, trends)
  • Content examples (30+ examples)

Example:

Type this into the chat
# In the body of the skill (inline):
## Analysis steps
1. Extract the key metrics
2. Compare against benchmarks (see references/benchmarks.json)
3. Identify anomalies (more than 20% off the average)
4. Write an executive summary (150 words max)

# In references/benchmarks.json (not in the body; numbers are illustrative):
{
  "email_open_rate": {"good": 25, "average": 20, "poor": 15},
  "conversion_rate": {"good": 3.5, "average": 2.0, "poor": 1.0},
  ...200 lines of data...
}

Subagents inside skills

Some tasks inside a skill are too heavy for one agent (an agent is an autonomous task executor):

markdown
## Step 3: Competitive analysis
Delegate to the `competitor-researcher` subagent with these parameters:
- The list of competitors from references/competitors.json
- Task: collect data for the last 30 days
- Return: JSON with metrics for each competitor

The main agent waits for the result → continues with step 4.

Worth knowing (as of October 2026): subagents in Claude Code run in the background by default. If step 4 depends on the result, say explicitly in the instructions that it has to wait. And you can run an entire skill in a separate context with the context: fork field in the frontmatter.

🎨 Picture this: a subagent inside a skill is like a foreman hiring workers for a specific stage. The foreman (the main agent) runs the construction site. For the foundation stage, he hires diggers (the subagent). They dig, and the foreman doesn't spend his own energy. The diggers leave, and the foreman carries on.

Why: competitive analysis is a long task (lots of requests, lots of data). By delegating it to a subagent, you:

  • Keep the main agent's context clean
  • Can run several subagents in parallel
  • Let the subagent use a cheaper model (Haiku for data collection)

How to audit your skill library once a quarter

Every 3-6 months:

  1. Check Capability Uplift skills: test the model without the skill. If it does well, delete the skill.
  2. Update data in reference files: have competitor prices changed? Update them.
  3. Look at usage: which skills haven't been used in 60+ days? Are they worth keeping?
  4. Find duplicates: two skills doing similar things? Merge them.

🎨 Picture this: a skill audit is like cleaning out the garage once a quarter. Haven't touched this tool in a year? Why is it taking up space? This one duplicates that one, so I merge them. This one is outdated and the new one is better, so out it goes. A garage should be a workshop, not a museum.

Your skill library should stay lean: not a collection for its own sake, but a working tool.

Practice

Assignment: Sort 5 potential skills into the two types

  1. Take 5 tasks you do regularly:
    • For example: writing emails to clients, doing data analysis, creating social media posts, preparing presentations, doing code review
  2. For each task, decide: is it Capability Uplift or Encoded Preference?
    • Ask yourself: "Can the model do this without my personal experience?"
    • If YES → Capability Uplift
    • If NO (it needs my personal style/process) → Encoded Preference
  3. For each skill, decide: global or project?
  4. Estimate the size: what goes inline, what goes into reference files?
  5. Bonus: create one Encoded Preference skill right now. Pick the most personal task of the five.

Tools and resources

  • ~/.claude/skills/<name>/SKILL.md: global skills (create the folder if it doesn't exist yet)
  • .claude/skills/<name>/SKILL.md: project skills
  • Claude Code Skills documentation: the official guide to skills
  • /skill-doctor: checks the health of your skills in Claude Code (the command appeared in 2026; for the list of commands see the documentation)
  • /skills: the command for viewing installed skills

Key takeaways

Encoded Preference Skills = your competitive moat. Encode your processes: a competitor can't copy them, and the model can't guess them.

Capability Uplift Skills age as models get updated. Check them every 3-6 months, and don't carry dead weight.

A skill over 500 lines is a warning sign. Big data goes into reference files, logic goes into the body.

Next lesson

→ Evals: self-improving skills: how to test and improve skills based on data

The mark stays in this browser only and is never sent anywhere. My progress