Skills, distilled — and where they're going

Eleven chapters, one throughline: skills are recipes, descriptions are triggers, structure matters, primitive choice matters, composition unlocks scale. If you remember nothing else, remember that sentence — it's the whole book in 12 words.

Well-designed skills name what users say. Not what the code does. The description should read like a sentence you'd hear in a chat: "transcript", "deploy", "summarise this article". Not "calls v3 endpoint", not "uses readability-extractor library".

Claude only sees the description at trigger time. If the description speaks engineer, only engineer-shaped prompts fire it. Speak the user's vocabulary and the skill activates when it should.

Every invocation re-reads SKILL.md. So keep it scannable. Top headings, short lists, numbered steps where the order matters. If a section is heavy — long examples, full prompt templates, edge-case tables — move it to references/ or templates/ and link from the body.

Claude only follows those links when the body says to. Heavy detail stays cheap until it's actually needed.

Every skill has two doors: the explicit /slash-command and the implicit description-match. Good skills work through both. The slash is there for "I know exactly what I want"; the description is there for "I just said something natural."

Don't force one path. Don't pick a skill name that's awkward to type, and don't write a description so tight it never matches. Both doors stay unlocked.

When a skill assembles output — an email, a prompt, a config file — keep the template in a supporting file with {{PLACEHOLDER}} slots. The skill body fills them. Two wins: the template is reusable across skills, and you can edit the shape without touching the recipe.

Templates are also easier to read for humans than the same content inlined in a SKILL.md as a 40-line code block. The recipe stays a recipe; the artifact stays an artifact.

When a skill starts wanting to do five things, split it. The pattern that scales: one orchestrator skill calls a few worker skills, and the workers may dispatch agents. Three layers max. Skills calling skills is a feature, not a smell — it's how complex behaviour stays testable.

The book-builder skill is a real example: an orchestrator that knows the book shape, worker skills for chapter builds, agents for parallel work. None of those three pieces would be readable as a single 500-line SKILL.md.

One skill, five jobs. Tempting, because each new request feels close to the last one. Resist. A skill that does five things is harder to test, harder to trigger correctly, and harder to trust than five skills that each do one.

The cure is boring: when in doubt, split. Each piece gets its own description, its own body, its own slash-command. The orchestrator pattern (above) is how you keep the five pieces feeling like one feature.

The skill system is young. The shape we've been showing across twelve chapters is what works today — but it's not the final form. A handful of things are clearly on the way, and worth being ready for.

Four lines. If you only carry four things from twelve chapters, these are the four.

The first tab is what all five patterns look like when they live in the same skill. The second is the checklist worth running before you call something "done".