How to write a SKILL.md for Claude Code

A skill is a folder with one text file in it. Most of the work is in the first two lines, because that is how Claude decides whether to use it.

Where it goes

One folder per skill, with a SKILL.md inside. Personal skills live in ~/.claude/skills/<name>/SKILL.md; skills for one project live in .claude/skills/<name>/SKILL.md inside that project. Restart the session after adding one.

The two lines that matter

---
name: session-handoff
description: Use when the user ends a session. Writes a HANDOFF.md.
---

The name is the folder name. The description is what Claude reads to decide whether the skill applies, so write it as a trigger, not as a title. Say when to use it, then what it does. Compare:

• Weak: "Helps with notes." It matches everything and nothing.
• Better: "Use when the user ends a session or asks for a handoff. Writes HANDOFF.md from real git output."

The body: steps, one example, when to skip

1. One goal sentence and a line on when not to use it.
2. Numbered steps in the order they happen. Verbs first: "Run git status --short", not "It is useful to check status".
3. One worked example: a real input and the output you want. It teaches more than a paragraph of rules.
4. A check at the end: what the agent confirms before it says it is done.

Keep it short. Ours run from 15 to 48 lines. If a skill needs more, move the reasoning into a separate file next to it (we use a short WHY.md) and keep SKILL.md to the steps.

Test it before you trust it

1. Should trigger: start a fresh session and ask for the task in plain words, without naming the skill. See whether it follows the steps.
2. Should not trigger: ask for something nearby that it does not cover. If the skill jumps in anyway, tighten the description.
3. Read it as a stranger. Any step that needs your memory to make sense will fail in another session.
4. Scan for secrets. Keys, paths with your name and private project names have no place in a file you share.

Common mistakes

• A description that says what the skill is, not when to use it.
• Rules with no example, so the agent guesses the format.
• Three goals in one skill. Split it.
• No stop rule on anything that loops or searches.

Examples to read

Three small skills in this style, MIT licence, free to copy: loop-stop, session-handoff and ask-before-building. We tested them by hand on our own projects; we have not measured them on other people's workflows.