Anatomy of a skill

A skill is a single invocable action, authored to a strict shape so the agent can find it, fire it, and trust what it does. Here is every part — and why it exists, and which pillar it serves.

Frontmatter

---
name: build-sprint
description: Work one Sprint's issues in two phases — PLAN then EXECUTE...
---

• name = the directory = the command. Claude Code has no alias field; /-autocomplete and invocation key off the directory name, and name: is display-only — they must stay identical. Renaming a skill is a git mv of the directory plus a cross-reference sweep. (Pillar: tools — the catalog stays addressable.)
• description is the trigger. It's how the agent decides to fire the skill, and it is always-on — the / menu lists every description on every session. So it's packed with Use when… / NOT… and how it differs from siblings, then kept tight, because every word loads each turn. (Pillars: tools and context.)

This two-tier shape is progressive disclosure: the tiny description is the only always-on cost, the full body loads only when the skill fires, and its heavy reference (docs/agents/*) loads only when a step needs it. One agent carries dozens of skills but pays for just the one it's using.

The body contract

The body must declare four things, or the verb decays into a slogan:

• Task class — answered by the verb: build-sprint creates, qa-code audits, optimise-context trims, find-learnings discovers, source-a-skill acquires, check-reasoning reasons. The taxonomy is build / qa / optimise / find / source / check, plus the incidental be / tidy / fyi and standalone single-word skills like vet and debug. See the verb taxonomy.
• Allowed tools — what it may touch.
• Direct vs fork — does it run in-thread, or dispatch a subagent to gather independently?
• The verifiable artifact — what is concretely true once it's done.

The heart

Every good skill marks its heart — the one step that carries it, flagged **This is the skill.**. For brainstorm it's the Socratic pin-down; for check-reasoning it's the independence gate. Naming the heart stops a skill from drifting into a vague checklist. (Pillar: tools — each skill keeps one clear job.)

Guardrails and altitude

A writing skill carries tiered surface-then-confirm (see Guardrails); a pure-read one carries none. And each skill has an altitude — L0 (one artifact), L1 (one pillar's set), L2 (the whole harness) — signalling its blast radius. (Pillar: guardrails.)

The full authoring recipe is build-claude-skill; the quality bar is docs/agents/skill-quality.md.