Reference Guide
How Skills Work
Everything about Agent Skills: what they are, how agents load and use them, how to write one that actually changes behavior, and how to know when it is ready to ship.
What is a skill
A skill is a SKILL.md file that lives in a project and tells an AI agent how to handle a specific, repeatable job. When an agent encounters a task that matches the skill's trigger, it loads the file and follows the instructions.
Without skills, every coding agent starts from the same generic starting point. With skills, an agent can show up to a project already knowing the exact commands, the real pitfalls, the team conventions, and the verification steps - without you having to explain them each time.
Skills are not documentation. Documentation is written for humans who read it once to understand something. Skills are written for agents who load them on demand to do something. The difference changes everything about how you write them.
Anatomy of a skill
A working skill has four parts. Every part is necessary. None are optional once the skill is in use.
YAML
Frontmatter
The match surface. The description field is what the agent reads when deciding whether to load this skill. It is the most important line in the file.
Section
When to trigger
Plain-language expansion of the description. Names the exact actions, errors, or user requests that should load the skill - specific enough that the wrong kind of request clearly does not match.
Section
Procedure
Numbered steps with exact commands and real code. Not approximations. Not descriptions of commands. The exact thing to run or the exact file to create.
Section
Pitfalls
The specific, real failure modes this exact workflow produces. Not generic cautions. Each entry names the concrete wrong thing that will happen and the exact fix.
Writing the trigger
The description field in the frontmatter is not a summary of the skill. It is the trigger. The agent reads it when deciding whether to load the skill - nothing else.
Write it as a sentence that begins with "Use when" followed by a specific condition. That framing forces you to name the exact situation rather than the general topic.
Bad trigger
description: Covers database setup.
A topic, not a condition. This loads for every database question, burning context on jobs the skill does not help.
Good trigger
description: Use when adding or changing a Drizzle schema on a live Neon database, generating a migration, or resolving drift between schema.ts and the deployed database.
Three specific conditions. Excludes "how do I query the database" and "which ORM should I use" without saying so explicitly.
The trigger test: write out three requests that should load the skill and two that should not. Read the description aloud. Does it naturally match the first group and exclude the second? If it matches everything loosely, narrow it.
Writing the procedure
The procedure is numbered steps. Every step has one job. If a step requires a decision, the skill gives the agent enough information to make it without looking anything up.
Four rules for procedure steps
- 01Show the real command, not a description of it. "Run the migration command" is useless.
pnpm drizzle-kit migrateis a step. - 02Put the explanation after the code, not before it. The agent acts first; it reads why after.
- 03Reproduce what is necessary; link what is not. A skill is not a copy of the documentation. Show the critical snippet; link the rest.
- 04If the step can fail, that failure belongs in pitfalls - not as a warning inside the step itself. Keep steps clean; pitfalls handle the edge cases.
The clearest sign of a weak procedure is a step that says "appropriately" or "as needed." Those words are a placeholder for a decision the skill author did not make. Make the decision and write it down.
Writing pitfalls
The pitfalls section is why the skill is worth writing. It encodes what went wrong the first time - or what will mechanically go wrong if the agent follows the happy path without knowing the trap.
A pitfall entry is two things: the concrete wrong thing that happens, and the exact fix. Cautions ("be careful about X") are not pitfalls. Cautions give the agent nothing to act on. Failures do.
Caution - not useful
Make sure to handle errors properly.
Pitfall - useful
Calling drizzle-kit push against a production database treats a column rename as a drop-and-add and silently destroys the column's data. Use generate + migrate anywhere that holds real data.
Before shipping, audit each pitfall: has this actually happened? A theoretical pitfall ("you might forget to...") adds noise and trains agents to over-check. If you cannot name the real incident or the mechanical inevitability, cut the entry.
Testing a skill
A skill that compiles is not a skill that works. Five checks before shipping, in order:
1
Trigger probe
Write three requests that should trigger the skill and two that should not. Read the description. Does it match the first group and exclude the second? If not, narrow the trigger.
2
Procedure walk-through
Follow every step in the actual repo as if you have never seen it. Any moment where you need to look something up means that thing should be in the skill.
3
Pitfall audit
For each pitfall: is the failure concrete? Is the fix specific? Is it still true? A wrong pitfall is worse than a missing one. Cut anything theoretical.
4
Scope test
State in one sentence what this skill does. If you cannot, it is too broad. If you can state two different things, it is two skills.
5
Staleness check
Verify every command, path, and version claim against the actual codebase today. If a fact needs a date to be verifiable, add the date.
The field test
The only real test is running the skill against a live agent. Drop the file in .claude/skills/<name>/SKILL.md, open a fresh session, ask one of your trigger requests, and watch. Did the agent load the skill? Did it follow the procedure? Did it hit the pitfalls you documented?
Everything else is a pre-flight check. This is the flight.
Composing skills
A single skill handles one job. When a workflow crosses multiple jobs, three patterns connect them without turning them into a monolith.
Entry router
A domain has multiple sub-tasks an agent cannot reliably distinguish from one description.
One skill maps requests to the right specialized skill. It holds the routing table, not the procedures. If it starts accumulating steps, those steps belong in a specialized skill.
Reference files
A skill has supporting detail (a schema, a role map, a checklist) that most agents will not need on every run.
The main SKILL.md covers the workflow. Reference files (reference/*.md) hold the depth and are loaded on demand. Each reference file covers one thing.
Skill chain
Two skills are naturally sequential - write the skill, then test it - or one skill has a well-known follow-up outside its scope.
Skills reference each other via relatedPaths and inline 'after this, see' notes. Each skill stays complete on its own. The chain is navigational, not procedural.
When in doubt, split. Two focused skills are always cheaper to reason about than one bloated one. The one rule that applies to all three patterns: never reproduce content from another skill inline. Reference by slug. Two sources of truth will drift apart.
Shelf life
A skill goes stale the moment the codebase moves past it. A stale skill is worse than no skill: it gives agents confident, wrong instructions.
The discipline is to update the skill in the same changeset as the change that makes it wrong. If a session reveals that a pitfall is no longer true, the skill update is part of that session - not a future task.
Staleness signals
- -A command in the skill no longer exists or has changed its flags.
- -A file path the skill mentions has moved or been deleted.
- -The skill describes a "current" design system, tool version, or API that has since changed.
- -An agent following the skill produces a result that does not match what the skill promises.
Ready to write one
Browse the library to see real examples and copy the ones closest to your use case.
Get Smarter About AI Dev
New tutorials, open-source projects, and deep dives on coding agents - delivered weekly.
One email per weekReal code, not theoryFree forever