Claude Skills are one of those features that look small in the changelog and turn out to reorganize how you build agents. A skill is a self-contained unit — a markdown file plus optional resources — that teaches Claude how to do one specific thing well. The agent loads the skill on demand, follows the instructions inside, and produces a far more reliable result than the same prompt would on its own.
This post unpacks the model: what a skill actually is, how Claude decides when to use one, how to write your first skill, and the patterns that separate skills that hold up in production from skills that quietly rot.
What a Skill Is
The shape is intentionally simple. A skill is a folder with at least one file:
my-skill/
├── SKILL.md # the agent-facing instructions
├── examples/ # optional reference material
│ └── example1.txt
└── scripts/ # optional code the skill can call
└── helper.py
The SKILL.md has frontmatter describing when the skill should activate, and a body explaining how to do the thing:
---
name: refactoring-react-class-components
description: Use when migrating React class components to function components with hooks. Triggers on files containing class extends Component or class extends React.Component.
---
# Refactoring React Class Components
When you see a class component, follow these steps...
When the agent encounters a situation that matches the skill's description, it loads the SKILL.md, follows the instructions, and (when relevant) reads the examples or invokes the scripts. The output is the same kind of thing the agent would produce anyway, but with consistent quality, because the skill enforces the steps.
That's the whole abstraction. Everything else is convention.
How Claude Decides to Use a Skill
The activation logic is what makes skills feel like magic the first time. Anthropic's framing: skills are teachers, not tools. When the agent is starting a task, it looks at the descriptions of all available skills and picks any whose triggers match. Multiple skills can activate at once; their instructions compose.
Three things matter for activation reliability:
- The description is everything. Anthropic's recommendation — and our experience — is that the description should be very specific about when to use the skill, with concrete trigger phrases the user might say or the agent might encounter. "Use when X" is much better than "About X."
- Skills compose. A "writing tests" skill and a "TypeScript style" skill can both activate on the same task. They are read one after another and Claude treats them as a single instruction set. Design skills to compose rather than replicate each other.
- Skills should be small. A 200-line SKILL.md beats a 2000-line one. If a skill is doing too much, split it.
For a comparison with how MCP gives the agent access to tools rather than guidance, see Top 10 MCP servers for Claude Code. MCP gives capabilities; skills give wisdom.
Writing Your First Skill
A useful first skill is one you have asked Claude to do twice and gotten different results both times. Examples:
- "Write a Postgres migration in our project's style."
- "Generate a release note from a list of merged PRs."
- "Convert a curl example to our internal Go HTTP client."
Pick one. Then:
mkdir -p .claude/skills/postgres-migrations
cd .claude/skills/postgres-migrations
Create SKILL.md:
---
name: writing-postgres-migrations
description: Use when adding a new Postgres migration. Triggers on requests to "add a column", "drop a column", "create a table", or any change that requires a new file under db/migrations/.
---
# Writing Postgres Migrations
We use sqitch for migrations. Each migration has three files: deploy/, revert/, and verify/.
## Steps
1. Compute the next migration number with `ls db/migrations/deploy/ | sort | tail -1`.
2. Create three files under `db/migrations/{deploy,revert,verify}/{N}_{name}.sql`.
3. Deploy: the actual change. Always wrap in a transaction.
4. Revert: the inverse. Even for additive changes — make it safe to undo.
5. Verify: a SELECT that fails if the migration did not apply.
## Style
- Use lowercase `snake_case` for column names.
- All NOT NULL columns must have a default OR be backfilled in the same migration.
- Index changes go in their own migration, never bundled with schema changes.
- Foreign keys are declared inline, never as a follow-up.
## Avoid
- ALTER TABLE ... ADD COLUMN x NOT NULL without a default — locks the table.
- Multi-step migrations in a single file. Split them.
Now in Claude Code: "Add a subscription_tier column to the users table. Default to 'free'." The agent loads the skill, knows to check the migration number, knows to write all three files, knows to add a default. The output is consistently shaped because the skill encoded what "consistently shaped" means in your project.
Patterns That Hold Up
Once you have a few skills, certain shapes survive contact with reality.
Skills as project memory. The most durable skills capture a decision your team has made — naming conventions, deployment process, preferred test style. When a new engineer ships a confusing PR, write a skill instead of writing a comment. The next agent (or human reading the skill) gets the institutional knowledge.
Skills with examples. A skill that says "format errors like this" should include a couple of examples. Claude reads them and matches the pattern. Three lines of example often beat three paragraphs of description.
Skills that call scripts. When part of the work is deterministic — bumping a version, running a code formatter, reading a CSV — put it in a script the skill invokes. The agent gets to focus on the genuinely judgmental parts.
Skills with explicit "do not." Telling the agent what not to do is often more useful than telling it what to do. "Do not add error handling to functions that the caller validates inputs for" prevents an entire class of over-engineering.
Patterns That Quietly Rot
Two failure modes show up over time.
Skills that go stale. A skill written six months ago references a build command that no longer exists. The agent dutifully follows it and produces a broken commit. The fix is to keep skills short and close to the things they describe. A skill in your repo should be a candidate for code review whenever the underlying thing changes.
Skills that expand into manuals. A skill grows from 200 lines to 800 lines, picks up edge cases, adds caveats. At that point it stops being read carefully. If a skill is becoming a manual, split it: extract the "writing tests" subsection into its own skill, leave the original tighter.
Skills + MCP + Sub-Agents: The 2026 Stack
Skills become much more powerful in combination with two adjacent features.
MCP servers give the agent access to external state — databases, issue trackers, observability. A skill can reference "use the linear MCP to look up the parent issue" and the agent does it.
Sub-agents let one agent spawn another with a different role and a different skill set. A "code review" sub-agent can be given just the relevant skills and pointed at a diff.
This is where the L5 orchestration story becomes concrete: a top-level agent with skills that knows when to delegate to a sub-agent, with budget controls and traces tracking what each step did. We cover the broader pattern in How to run AI agents in production and how it ties to routing in AI model routing explained.
Anti-Patterns
- One skill per file in the codebase. Too granular. Skills are about types of work, not files.
- Skills that contradict each other. If two skills could activate at once and disagree, the agent's behavior becomes unpredictable. Keep skills mutually consistent.
- Skills that try to override Claude's judgment. "Always use
varin JavaScript" is fighting the model. Use skills to encode taste within what Claude already does well. - Hard-coding model-specific behavior. Avoid "Claude Sonnet 4.6 will respond best if..." — those workarounds rot fast (Sonnet 4.7/4.8 will land soon enough).
Distribution and Sharing
Skills are just folders, so distribution is git. Common patterns:
- Per-project:
.claude/skills/in your repo, checked in. Every clone gets the same skills. - Personal:
~/.claude/skills/for your own conventions across projects. - Team registry: a separate repo of shared skills, pulled in via a script or git submodule.
- Public: the anthropics/skills repo and a growing ecosystem of community skill packs.
The Router One internal team uses two layers: project-specific skills for the codebase + cross-project skills for company conventions (postmortem format, release process, on-call etiquette). Both live in git so changes get reviewed.
FAQ
Are skills the same as system prompts? No. A system prompt is what the agent sees on every turn. A skill is loaded only when its description matches the situation. You can have hundreds of skills; only the relevant few get loaded for a given task.
Do skills work with Codex CLI? Skills are an Anthropic concept. Codex CLI does not load them. The closest equivalent in the Codex world is the project's own README plus targeted prompt injection. See Codex CLI alternative.
Can the agent edit skills? Yes — and this is a useful pattern. When you correct the agent and tell it the rule, you can ask it to update the relevant skill so the correction sticks for next time.
Should skills include code? Sparingly. A skill that demonstrates a pattern with a 10-line example is fine. A skill containing a 500-line library should probably be a script the skill calls, or a separate utility.
How do skills interact with privacy? Skills are content; they ride along in the prompt. Do not put secrets, internal-only URLs you would not paste into a chat, or anything that would be a problem in your model provider's logs. For Router One routing, skill content is treated like the rest of the request — proxied without persistent storage.
What about Skills marketplaces? Several public registries are emerging in 2026. Treat them like npm packages: useful, but vet what you install. A skill is instructions the agent will follow; a malicious skill is a vector.
Conclusion
Skills are the place where your team's knowledge gets to compound. Every time you correct an agent and feel a flicker of "I have explained this before," that is a skill waiting to be written. Start with three or four high-value skills around your most-repeated tasks, keep them small, review them when the underlying thing changes, and let them accumulate.
For a step-by-step on getting Claude Code itself running, see the setup guide; for the tools that make skills materially more powerful in agentic loops, see our MCP servers list.