The Anatomy of a Skill File
What a Skill actually looks like on disk: a folder, a short frontmatter block, and a body of plain instructions.
It's simpler than it sounds
After the last two chapters, a Skill might sound like some special piece of engineering. It isn't. Strip away the concept and what's left is genuinely simple: a folder, containing one file, written in the same kind of plain document you'd write a set of instructions in for a new coworker.
my-skill/
SKILL.md
That's the minimum. Everything else, extra reference files, scripts, examples, is optional, added only when a skill genuinely needs more than one page can hold.
Two parts inside that one file
SKILL.md has two pieces: a short frontmatter block at the very top, and the actual instructions below it.
---
name: pr-review-checklist
description: Use when reviewing a pull request, to apply this team's standard review checklist consistently.
---
## What to check, in order
1. Does the change include a test for the new behavior?
2. ...
Why the split matters
Separating a short summary from the full body is what makes the matching from the last chapter cheap. Deciding relevance only requires reading name and description, a few lines, across every available skill. The potentially long body only gets read for the one skill that actually matched. Without that split, deciding what's relevant would require reading everything, every time, which defeats the purpose of having separate, focused skills in the first place.
Once a skill's instructions grow past what fits comfortably on one page, it's common to keep the main SKILL.md short and move deeper material into additional files alongside it, referenced from the main file by name. The next few chapters cover exactly when and how to do that.
If you have access to any existing Claude Code skills, open one up and find its frontmatter. Read just the name and description, nothing else, and ask yourself: could I guess what this skill is for from those two lines alone? That's the exact test a real match has to pass.