The instruction you write once instead of every session

There is a moment every few days where you type the same correction again. Use our button component. Do not add a dependency for that. The dates in this project are always ISO. You said it on Tuesday, the session ended, and the knowledge ended with it.

A skill is that instruction, written once, in a file the agent picks up on its own when it becomes relevant.

That is the whole concept, and the rest of this page is the mechanics, the judgement about what belongs in one, and the debugging — because the failure mode is not writing a bad skill, it is writing a good skill that never loads.

What a skill is on disk

A folder with a markdown file in it:

.claude/skills/
  cc-brand/
    SKILL.md
    references/
      token-reference.md
      motion-and-craft.md
    assets/
      AppShell.vue
      cc-tokens.css

SKILL.md opens with frontmatter carrying two things that matter:

---
name: cc-brand
description: Implements UI in the CC design system for Vue. Use this WHENEVER
  building, styling, theming or reviewing any Vue interface, component, page,
  dashboard or form for CommitCycle — and whenever the user mentions CC UI, the
  brand blue (#693DFF), Plus Jakarta Sans, shadcn-vue, or "make this on-brand".
---

# CC Design System Implementor

Everything the agent should know, in ordinary markdown.

Nothing else is required. No build step, no registration, no configuration file. The folder exists, so the skill exists.

Why not just put it in the prompt?

Because you have to remember, every time, and you will not. More precisely: the times you forget are not random. They are the times you were moving fast, which are the times the agent had least context, which is exactly when the convention mattered most.

Why not just put it in AGENTS.md?

This is the real question, and the answer is the design of the whole feature.

AGENTS.md (or CLAUDE.md) is always loaded. Every turn, every session, every task, whether relevant or not. That makes it perfect for facts that are always true — the stack, the commands, the folder layout, the things never to do — and it means every line you add costs context on work that has nothing to do with it. A 900-line AGENTS.md is a tax on every request.

A skill is loaded only when it matches. What is always in context is its name and description — a couple of lines. The body is read only when the agent decides the task calls for it.

This is called progressive disclosure, and it works in three levels:

Which is why a skill can be enormous — a full design system, a compliance checklist, an API’s entire surface — without slowing down a request about something else. You are carrying a library, not a note.

What belongs where

The judgement that makes all of this work:

The common mistake is putting design-system-sized content in AGENTS.md, where it is loaded on every request including the ones about a build script. The other common mistake is putting the project’s stack in a skill, where it might not load at the moment it is needed.

The description is the whole trigger

If you take one thing from this page: the description is not documentation, it is the matching rule. It is the only part of your skill the agent sees before deciding whether to read the rest.

So write it in the words a person actually types. Not:

Brand implementation guidelines and component standards.

That matches nothing. Someone asking “make this look like our app” has not used any of those words. Instead:

Use this whenever building, styling, theming or reviewing any interface, page, dashboard, form or component for [product] — and whenever the user mentions [the brand colour], [the font], [the component library], or “make this on-brand”. Reach for it even when the request is just “build a settings page” or “style this card”.

Concretely, a description that fires reliably names:

• The verbs — building, styling, reviewing, migrating, drafting
• The nouns — the artefacts it applies to
• The literal strings — product names, hex codes, font names, library names
• The informal phrasings — “make it on-brand”, “the usual way”, “like the other pages”
• When to use it even though it does not look like it applies — this line does a surprising amount of work

Being over-inclusive costs a little context when it fires unnecessarily. Being under-inclusive costs you the entire skill, silently, forever. Bias towards firing.

Where skills live

Two places, and the choice matters more than it looks:

.claude/skills/ inside the project. It commits with the repository, so it is present on your other machine, in every future session, and for anyone else who clones it. Anything that describes this product belongs here.

~/.claude/skills/ in your home directory. Available in every project you touch, invisible to everybody else. This is for your own working style — how you like commits written, how you want documents structured.

The default should be the project. A skill that lives only on your laptop is one machine away from not existing, and it is the reason a project “only works properly when you run it”.

How do I know it fired?

Ask. Which skills did you use for that? is a reasonable question and gets a straight answer. What skills do you have available? lists them, which is the first check after installing one.

The stronger check is behavioural: start a fresh session, phrase a request the way a real user would — not the way the skill’s own documentation phrases it — and see whether the output follows the rules without you mentioning them. That is the only test that matters, because that is the actual condition of use.

Why is my skill not firing?

Notice that four of the five are description or placement problems. The content is rarely what is wrong.

Keeping SKILL.md short

Once loaded, the body is read in full — so length costs something, and the good structure is a short instruction file that points at detail.

SKILL.md              the rules, the decision order, what wins in a conflict
references/           the long material: token tables, API surfaces, examples
assets/               things to copy: components, stylesheets, templates
scripts/              things to run

The cc-brand skill in the example above is exactly this shape: the SKILL.md states the layer priority and the conflict rule in a few hundred words, and the token reference, the motion guidance and the ready-made shell components sit in files it points at. The agent opens the sidebar reference when it is building a sidebar and never otherwise.

Two things belong in SKILL.md rather than a reference file: the order of precedence (when two rules collide, which wins) and what not to do. Both are short and both are what the agent gets wrong when they are missing.

Skills, MCP, subagents, slash commands

Four things that get confused, on genuinely different axes:

Skills and MCP are complements rather than alternatives. The MCP server gives the agent a connection to your database; the skill tells it your schema conventions and which tables are never written to directly. Tools without instructions is the configuration most people have, and it is why the agent can reach everything and still do the wrong thing with it.

Installing one somebody gave you

1. Put the folder in .claude/skills/ (project) or ~/.claude/skills/ (personal).
2. Start a new session — an existing one has already built its list.
3. Ask what skills do you have available and check yours is listed by name.
4. Give it a realistic request and see whether the rules apply without being mentioned.

If step 3 fails, the folder is in the wrong place or SKILL.md is misnamed. If step 4 fails, it is the description.

The one worth installing on day one is a design skill. If you have an idea but no brand and no visual opinion yet, startpow.com will let you pick what you like, export, and download the result as a skill. Drop it in, and every screen the agent builds from then on arrives in your colours, your type and your spacing without you describing them again — which is roughly the difference between a product and a demo, for about ten minutes of work.

How many skills is too many?

There is a real budget, and it is not the one people worry about. The bodies are free until they load, so a folder of forty skills does not slow anything down. What is not free is the descriptions, which are all in context, all the time.

Forty vague descriptions is worse than five sharp ones for a second reason too: the more of them overlap, the less reliably the right one wins. Two skills that both plausibly cover “styling” means a coin toss on every UI request.

The practical shape is a handful of skills with clean boundaries, each of which you could describe in one sentence without using the word “and”. When you cannot, that is two skills.

A skill is instructions you agree to run

Worth saying plainly, because skills get passed around like themes and they are not themes.

A skill is a set of instructions an agent will follow, with your permissions, in your repository. A downloaded skill can tell an agent to install a package, to send a file somewhere, to treat a rule as more important than the ones you wrote. That is the same trust decision as running a script somebody sent you, and the fact that it is markdown rather than code makes it feel smaller than it is.

So: read SKILL.md before you install it, look at whatever else is in the folder, and be more careful with skills that ship scripts than with skills that ship documentation. A design system from a tool you chose is a very different proposition from a skill pasted into a forum thread.

The same applies in reverse when you publish one — anyone installing yours is extending you that trust.

Getting them to a team

Three routes, in increasing order of ceremony:

• Commit them to the repository. .claude/skills/ is in the repo, so cloning gets them. This covers most cases and needs no infrastructure at all.
• Ship them in a plugin. A plugin can carry skills along with commands and MCP servers, installed by name and updated centrally. Right when several repositories need the same conventions.
• Send the folder. Fine once, unmanageable by the fourth person, because there is now no answer to “which version do you have”.

The failure to avoid is the one where the skill exists only in one person’s home directory. The project then behaves differently depending on who is driving, and nobody can see why.

The fastest way to write your first skill

Do not start from a blank page. Blank pages produce generic rules, and generic rules are the ones the model already follows.

Instead: work normally, and pay attention to what you correct. The third time you say the same thing — the third time you point out the date format, or the component, or that we do not use that library here — say:

Turn what you just learned into a skill. Write the description so it fires whenever someone asks for anything in this area, including informal phrasings. Keep SKILL.md short and put the long detail in a references file.

Your corrections are already the exact content a skill needs. They are specific, they are real, and they are the ones that were actually being got wrong — which is a much better starting set than anything you would think to write in advance.

Hacks that make a real difference

• Show, do not only tell. One worked example of your convention outperforms three paragraphs describing it. Models are extremely good at pattern-matching from an example and merely obedient about following a rule.
• One skill per concern. A single “our standards” skill covering design, testing and deployment fires on everything and applies to nothing well. Split it.
• Say what wins. Every skill that contains more than one source of guidance needs a sentence saying which one takes precedence in a conflict. Without it, the model picks, and it picks differently each time.
• Write the negative rules. Do not introduce a second component library. Do not add dependencies for something the standard library does. Negative constraints are followed more reliably than positive ones and are almost always the thing you actually cared about.
• Version it with the code it describes. A design skill in the repository changes in the same commit as the tokens it documents. A design skill on your laptop drifts within a fortnight and then confidently teaches the agent last month’s colours.
• Test with a cold session and a lazy phrasing. “make the settings page” is how the request will really arrive. If the skill needs the well-formed version to fire, it does not work.
• Let old skills die. A skill describing a convention you abandoned is worse than no skill: it is a confident, always-available instruction to do the wrong thing.

If you are not on Claude Code

Skills-as-folders are a Claude Code feature. Other agentic tools read a single always-loaded instructions file, and the near-universal convention is AGENTS.md at the root of the repository.

The content transfers directly. What does not transfer is the selective loading — everything in that file is paid for on every request — so the discipline is different: keep it to what is always true, put the long material in ordinary documentation, and point at it from the file rather than pasting it in.

Either way, the underlying move is the same one, and it is the highest-leverage habit in agentic development: the second time you explain something, write it down where the agent will find it. The rest of the setup that sits around this — the repository, the model, the host, the stack, the guardrails — is six decisions long.