The frontmatter is two fields. The body is Claude's reading material — direct instructions in markdown, short enough to re-read on every invocation.
Chapter 2 showed you how to write the description — the bit Claude reads at session start to decide whether to invoke. This chapter is about everything that lives below the second --- line: the body Claude actually follows once the skill fires.
The short version: two required frontmatter fields, then markdown the way Claude likes to read it. Direct verbs. Numbered steps. Headings Claude can scan. Short enough that re-reading it on every invocation doesn't tax the context.
Every SKILL.md starts with a YAML block between two --- lines. Only two fields are strictly required:
name — must match the directory name. This is how the skill is addressed.description — the trigger. Covered in depth in Chapter 2.That's the whole list. You'll occasionally see optional metadata — metadata.type, version tags, custom keys — and some tooling reads those. Claude itself only needs name and description. Anything else is bookkeeping for tools that wrap around skills.
Here's what minimal vs maxed-out looks like side by side:
When the skill triggers, Claude reads the body top-to-bottom and follows it as instructions. This is the part people most often get backwards: the body isn't documentation aimed at humans. It can be readable to humans (and often is), but its actual reader is Claude, on duty, mid-task.
What that means in practice:
Think of it as writing a short tutorial for someone who already knows the language but hasn't done this particular task before. Crisp. Imperative. No throat-clearing.
The top-level # heading is the skill's display title (usually the same as name, in Title Case). The ## headings are major sections. Stick to a small vocabulary of conventional names — Claude pattern-matches on these during retrieval, so predictable headings mean predictable behaviour.
| Heading | What goes there |
|---|---|
# Skill Name | One-paragraph what-the-skill-produces. Sets context. |
## When to use | The bulleted conditions under which this skill is the right answer. |
## Workflow / ## Usage | Numbered steps. Concrete commands. This is the recipe. |
## Examples | Short, copy-pasteable input → output samples. |
## Files in this skill | Directory tree of supporting files with one-line each. |
## Notes / ## Edge cases | Caveats, things that look right but aren't. |
You don't need all of them — most skills use three or four. But picking from this set beats inventing names like "How it Works" or "Background" that don't tell Claude (or you) what to expect underneath.
Here's the central decision when writing the body: does this content live in SKILL.md, or does it live in a separate file SKILL.md links to?
The rule of thumb is about reading cost. Claude re-reads SKILL.md on every single invocation of the skill — that's tokens spent every time. Supporting files only get read when SKILL.md actually points Claude at them. So:
Rule of thumb for total SKILL.md size: under 200 lines is comfortable, 200–500 is verbose, over 500 is almost always wrong. If your SKILL.md is creeping past 500 lines, there's content in there that doesn't need to be loaded every time.
If you find any of these in a SKILL.md you wrote, it's a tell that the file needs trimming:
scripts/ that SKILL.md references.The fastest way to internalise good shape is to read good examples. Three skills, three sizes, three different shapes — all valid, all working in production.
The poster child for "small SKILL.md". Three commands, a list of supported URL formats, a small ## Output section with a critical rule, and a few notes. No supporting files beyond a single scripts/get_transcript.py. Zero ceremony.
The middle case. Three different build paths, a list of constraints, and explicit links out to templates/build-chapter.md, references/voice-rule.md, and references/palette-registry.md. SKILL.md tells Claude which file to read for the deep instructions, but doesn't carry them inline.
The upper bound of what an inline SKILL.md can reasonably hold. Deep instructions on caching, thinking, tool use, model migrations — all in one file because every section is hot-path for the same trigger ("imports anthropic"). When in doubt about a skill that long, ask: does every invocation really need every section? If yes, keep it inline; if no, extract.
~/.claude/skills/youtube-transcript/SKILL.md, ~/.claude/skills/book-builder/SKILL.md, and whichever claude-api bundle ships with your CLI. Reading working skills beats reading any guide.The genre shift takes some getting used to. Documentation hedges. Tutorials chat. SKILL.md does neither.
| Instead of (human voice) | Write (agent voice) |
|---|---|
| "You might want to consider reading the config first." | "Read config.json first." |
| "It's usually a good idea to validate the input." | "Validate the input against the schema in schemas/x.json." |
| "This skill uses the YouTube transcript API to fetch captions, which..." | "Run uv run scripts/get_transcript.py "URL"." |
| "Generally speaking, you should report progress as you go." | "After each step, print one line: step N: done." |
The pattern: direct verbs, concrete artifacts, no hedging. Claude treats the SKILL.md as instructions it will execute. Vague language survives in human docs because humans interpret around it. An agent following instructions to the letter is much happier with letters.
Two versions of the "same" skill, side by side. The skeleton is the pattern you'll reach for most of the time. The bloated version shows what happens when too much content stays inline.
Skeleton: about 25 lines. Every section earns its place. Bloated: about 80 lines and growing, with <!-- MOVE TO references/ --> markers showing where the body is doing too much. The fix isn't more discipline — it's moving the long bits out to files SKILL.md links to.