How to write a Claude Code skill — and why most of them never fire

What a skill actually is

A skill is a directory containing a SKILL.md file: a block of YAML frontmatter, then markdown instructions. The agent sees only the metadata until something in your request matches — at which point the full body loads into context and shapes how the work gets done.

That is the entire mechanism, and understanding it explains everything else. A skill is not a function you call. It is a set of instructions the agent decides to read, based on one line you wrote.

.claude/skills/
  competitor-teardown/
    SKILL.md
    references/scoring-rubric.md
    scripts/fetch_pricing.py

Project-level skills live under .claude/skills/ in the repository. Personal ones live under your home Claude directory and follow you between projects.

The anatomy

The frontmatter carries the name and the description. The body carries the method.

---
name: competitor-teardown
description: Analyse a competitor's pricing page and produce a
  positioning gap report. Use when asked to compare pricing,
  study a competitor, or find positioning gaps.
---

# Competitor teardown

## When this fires
...

## Steps
1. ...

Two rules do most of the work:

• The description is a trigger, not a title. It should say what the skill does and the situations that should invoke it, in the words a user would actually type. "Marketing helper" never fires. "Use when asked to compare competitor pricing, study a rival's positioning, or find positioning gaps" fires reliably.
• The body is a procedure, not an essay. Numbered steps, explicit inputs and outputs, and a stated stopping condition. If you cannot say what "done" looks like, the agent cannot either.

Progressive disclosure — the part that keeps it fast

Everything in SKILL.md loads when the skill fires. Everything in files it merely points to loads only if needed. So the shape that scales is a short main file that names its references:

Keep SKILL.md to the method. Push the rubric, the long examples, the schema and the edge-case table into references/, and reference them by path with one line saying when to read each.

A 900-line SKILL.md is a context tax paid on every invocation, most of it for material that was irrelevant this time. A 120-line SKILL.md with four references is the same knowledge at a fraction of the cost.

The three reasons skills never fire

1. The description describes the skill instead of the trigger

By far the most common. Write the description for the moment of retrieval: which requests should pull this in. Include the synonyms a real person would use, including the sloppy ones.

2. Two skills overlap

If three skills all claim "content writing," the agent picks unpredictably between them. Give each a distinct territory and say in each description what it is not for. Boundaries are as load-bearing as capabilities.

3. It encodes knowledge the model already has

A skill that explains what SEO is adds nothing. A skill that encodes your rubric, your brand constraints, your output format, or a multi-step procedure with a verification gate is worth its place. The test: could the agent have produced this without the file? If yes, delete the file.

A practical build order

1. Do the task manually once and keep the transcript. That is your first draft.
2. Extract the procedure — the steps, the order, the decisions you made and why.
3. Write the description last, once you know what the skill really covers, and phrase it as trigger conditions.
4. Add a verification step at the end of the body. Skills that check their own output before declaring done are the ones you stop babysitting.
5. Test it cold in a fresh session by typing the request the way a user would — not by naming the skill. If it does not fire, the description is the bug, every time.

Common questions

Where do Claude Code skills live?

Project skills go in a .claude/skills/ directory inside the repository, so they travel with the codebase and the team. Personal skills live under your home Claude directory and are available in every project you work on.

Why is my Claude Code skill not being used?

Almost always the description. It needs to state the trigger conditions in the words a user would actually type, not summarise what the skill contains. Test by opening a fresh session and phrasing the request naturally without naming the skill.

How long should a SKILL.md file be?

Short enough that loading it is cheap — the method, the steps, the stopping condition. Push rubrics, long examples and edge-case tables into separate reference files the skill points at, so they load only when they are actually needed.

What makes a skill worth writing?

It encodes something the model could not produce on its own: your rubric, your brand constraints, your output format, or a multi-step procedure with a verification gate. If the agent would have done the same thing without the file, the file is overhead.