Skills

What a skill is

A skill is a self-contained package of procedure that the agent loads on demand. Each skill lives in a directory with a SKILL.md at its root. The agent always reads the metadata (name + description); it reads the body only when the description matches what you asked for, and it reads deeper reference files only when it actually needs them.

This pattern — short index, optional depth — is called progressive disclosure. It is what lets you ship a lot of knowledge without bloating every session’s context.

Skills vs slash commands

They are easy to confuse. The deciding question is who triggers it:

	Slash command	Skill
Trigger	You type /name	The agent, when the task matches its description
Best for	A fixed workflow you run by hand	Knowledge the agent should apply automatically
Location	.claude/commands/*.md	skills/<name>/SKILL.md

If you want to run a step, write a command. If you want the agent to know something and apply it without being told, write a skill.

When to build a skill

Build a skill when:

• You keep correcting the same class of mistake (e.g. “you forgot to scope the query to the current tenant”).
• There is a project-specific procedure the agent cannot infer (a deploy dance, a release checklist, a debugging recipe).
• You want the agent to follow a standard whenever relevant, not just when someone remembers to invoke a command.

Do not build a skill for:

• One-off prompts. Just type them.
• Anything CLAUDE.md already says. A skill is for procedure, CLAUDE.md is for standing facts.

How a skill is structured

A minimal skill:

my-skill/
└── SKILL.md

A skill that needs depth uses progressive disclosure:

my-skill/
├── SKILL.md          # short — the essentials; keep it focused
└── references/
    ├── patterns.md   # loaded only when needed
    └── advanced.md   # loaded only when needed

The SKILL.md carries frontmatter (name, description) and a body that tells the agent when to use the skill and how.

A generic example

A skill that enforces a code-review checklist:

review-checklist/
├── SKILL.md
└── references/
    └── checklist.md

SKILL.md frontmatter describes it as “use when reviewing a PR or evaluating generated code.” The body points the agent at the checklist in references/ and says when to load it. The agent then applies the checklist on its own whenever you ask it to review something — you do not have to invoke it.

Pitfalls

• A SKILL.md that is too long. If you dump a whole manual into the body, you defeat progressive disclosure — the agent loads all of it whenever the skill triggers. Keep the index short; push detail into references/.
• A vague description. The agent decides whether to invoke a skill by reading its description. If the description is “helps with code,” it will fire at the wrong times or never. Be specific about when.
• Duplicating a command. If you also wrote the same thing as a slash command, the agent has two paths to the same behavior and will use them inconsistently. Pick one.