You’ve told the agent the same thing four times this week. How to run the migration. How to investigate a failed contract test. Which of the three release scripts is the real one. Each time, you retype it, and each time, it’s slightly different.

You could put it all in CLAUDE.md. But then every session (one conversation with the agent) pays for it, whether or not the task has anything to do with migrations. A skill is the other answer.

What a skill is

A skill says how to perform a recurring task. It should activate narrowly. It’s reusable knowledge about how to act.

A skill lives in a folder. At the very least, that folder needs a SKILL.md file, which describes when to use the skill and how to do the work. Put the folder in .claude/skills/ for a project, in ~/.claude/skills/ for yourself, or ship it in a plugin (a bundle of skills, hooks, and other pieces you install together). You invoke a skill by typing /skill-name, or the agent loads it on its own when the task matches the description. (Skills follow an open standard, and Claude Code’s skills documentation covers its own extensions.)

It’s not totally wrong to think of a skill as a saved prompt. There are some nuances. For one, the agent can decide on its own to read up on a skill and add it to its context. That’s usually what you want. And skills let you load supporting detail only when it’s needed.

That saves you from shoving everything into your instruction file, which is CLAUDE.md for Claude Code (or AGENTS.md in Codex) and which the harness (the program wrapped around the model) loads according to directory scope, with descendant Claude Code instructions discovered on demand. If you write your descriptions well, a skill is a way to lazy-load instructions on an as-needed basis.

What a skill isn’t

A skill is not a capability grant. It doesn’t add any new tools to the harness. It can explain how to use a tool, and that tool could be a command-line program that happens to be on your machine. A skill’s allowed-tools field can pre-approve tools you already have, so you aren’t prompted (Configuring Skills covers it), but that never overrides a deny rule.

A skill can say a release requires passing tests. Your release infrastructure should enforce it. We’ll look at that gap between asking and enforcing in The Enforcement Ladder.

Anatomy of a skill

A skill has up to five parts:

• Name and description: The discovery surface. This is what the agent sees when it’s deciding whether the skill applies.
• Main body: The procedure the agent follows after the skill activates.
• Reference files: Extra detail that’s read only when needed.
• Scripts: Code the agent runs for deterministic work, so it doesn’t have to improvise.
• Assets: Templates the result is built from.

Here’s what that looks like for a database migration skill:

database-migration/
├── SKILL.md
├── references/
│   ├── postgres.md
│   └── mysql.md
├── scripts/
│   └── validate.sh
└── assets/
    └── report-template.md

The agent reads SKILL.md first. It only opens postgres.md if the migration is for Postgres. That’s the whole trick.

What makes a good skill

Here’s what separates a good skill from something that’s effectively a saved prompt. These are things the content does, and they live in the five parts above: the trigger goes in the description, the procedure, boundaries, inputs, proof, and retry safety go in the body, local evidence goes in reference files, mechanical helpers are scripts, and the deliverable is described in the body, with a template in assets if you need one.

• Trigger: The task it applies to, plus the near-misses where it should not activate.
• Procedure: Decisions and ordered steps, not just a list of virtues.
• Local evidence: Relevant examples, conventions, schemas, or documented constraints.
• Mechanical helpers: Existing commands or small scripts for repetitive, checkable work.
• Deliverable: A patch, reproduction, compatibility matrix, test report, or other inspectable result.
• Boundaries: What it must not modify, what needs approval, and when it should stop.
• Inputs: What the skill expects to be handed before it starts.
• Proof: How success gets demonstrated, not just announced.
• Retry safety: Which steps are safe to run again if something falls over halfway through.

Does this line change a decision?

Here’s a good test for every line in the body: does it change a decision?

“Handle errors properly” doesn’t. The model isn’t going to read that and think, “Oh, properly. Got it.”

Match how much you prescribe to how fragile the task is:

• An investigation: Specify the evidence you want back.
• Generated output: Hand it a schema.
• A destructive change: Give it the exact command. This is not the place for creative interpretation.

And before you write one at all, the missing knowledge should be specific enough to actually write down. If you can’t articulate what the agent keeps getting wrong, a skill isn’t going to articulate it for you.

What a skill costs

Skills load in stages, and every stage has a price tag. (Costs here are measured in tokens, the chunks of text a model reads and writes. Prompt Caching and Cost explains why they matter.)

• Name and description: For model-invocable skills, included in the discovery listing at roughly 100 tokens for a typical short description (one at the 1,024-character limit is closer to 250), whether or not the skill ever gets used. Thirty typical listed skills is about 3,000 tokens of overhead before you’ve typed a word. In Claude Code, manual-only skills with disable-model-invocation: true are excluded from that listing, so they incur no name/description overhead before invocation. The invocation table distinguishes these cases; use /context to measure the actual listing after its budget is applied.
• Body: For an inline skill, loads into the caller when invoked and stays in its context across later turns, subject to compaction. With context: fork, the body instead becomes the separate worker’s task and stays in that worker’s context while it runs; the caller receives its summarized result, not a session-long copy of the body. Running skills in a subagent explains the distinction.
• Reference files: Free until something actually reads them.
• Scripts: You pay for their output, not their source.

Keep SKILL.md under 500 lines. If it’s pushing past that, some of it probably wants to be a reference file.

Skills versus instructions

The line between a skill and an instruction in CLAUDE.md is pretty clean:

• Instruction: “All changes to billing must run the contract tests.”
• Skill: “How to investigate a failed billing contract test.”

An instruction is a rule that’s true all the time. A skill is a procedure for when something specific happens. See User and Project Instructions for the first kind.

Where to go next

The settings that control how a skill activates are in Configuring Skills. If you’re wondering whether what you have is a skill at all, Skill or Tool? draws the line between a skill and a tool, and Skill or Subagent? draws the line between a skill and a helper agent. And before you write one from scratch, Adapting Prior Art is worth ten minutes.

If you can’t say what the agent keeps getting wrong, don’t write the skill yet.