Skills

A skill is a packaged set of instructions the model loads when it decides they're relevant — not when a human remembers to ask. In Claude Code, a skill is a folder with a SKILL.md: front matter carrying a name and a one-line description, then the full procedure. The descriptions of installed skills stay resident in context; when the model judges a task matches one, it pulls in the body. That two-stage design — tiny trigger always present, full content on demand — is what lets you afford dozens of standing procedures where CLAUDE.md could afford none. This lesson: the gap skills fill, the craft of descriptions (the novel and genuinely tricky part), what earns skill-hood, and the trust question that comes with any instructions that activate themselves.

The gap: procedures without a rememberer

By now you have two homes for standing text: ambient rules loaded every turn (CLAUDE.md, lesson 8) and procedures a human invokes by name (commands, lesson 9). Between them sits a gap: procedures that should apply when circumstances warrant, even if nobody thinks to ask. Your migration checklist should activate when work touches migrations — including when the person driving doesn't know the checklist exists. Your team's PDF pipeline conventions should load when the task involves PDFs, not when someone remembers to type /pdf-rules.

With commands, the human is the trigger, and humans forget — the expert's checklist helps only when the expert is present and alert. A skill makes the situation the trigger. That's the entire feature, and its economics are what make it scale (lesson 20 does the arithmetic): a fifty-token description can guard a two-thousand-token procedure, resident cost near zero, full cost paid only in the minority of sessions that need it.

The description is a matching surface, not documentation

The body of a skill is prompt craft you already have (lessons 1 and 9): outcome, steps, boundaries, anti-instructions, written for a model that knows nothing else (lesson 11's blank-slate rule applies — the body must stand alone). The new craft is the description, because it's what the model triggers on, and it fails differently at each end of a dial:

Too narrow → silently missing. The insidious direction. The session completes, output looks plausible, and nobody knows the migration checklist never fired — absence doesn't announce itself. You shipped a migration without the checklist and learned about it from the incident.

Too broad → fires everywhere. The visible, merely-expensive direction: the body loads into sessions that didn't need it, paying context (lesson 2) and occasionally injecting inapt advice ("why is it talking about migrations in a CSS fix?").

The craft rules that set the dial:

• Describe task situations, not topics. "Use when writing or reviewing database migrations, or when a schema change is proposed" beats "Database best practices." The trigger is semantic matching against the live conversation, so name the moments, in the vocabulary a real task would contain.
• Include the surface forms. If tasks say "add a column," "alter table," "backfill" — those words belong in the description. Vocabulary overlap is what fires the match.
• Say when not to fire if the boundary is confusable: "...not for query optimization or ORM configuration."

And then test the trigger like the behavior it is — from both ends, because you're testing for a silence and silences don't test themselves. Give the model a task that should fire the skill and confirm it loads; give it a neighboring task that shouldn't and confirm it doesn't. Ten minutes when you write the skill, repeated when you edit the description. This is the only way to know the dial is set; everything else is hoping.

What earns skill-hood

Four criteria, all required — and each maps to a different home when it fails:

Criterion	If it fails
Procedural — steps and judgement, not facts	facts go in CLAUDE.md (8)
Conditional — relevant to a minority of sessions	always-relevant goes ambient (8)
Substantial — long enough that residency would hurt	short rules ride along free (20)
Deliberate-trigger not required	stakes want a human trigger: command (9)

That last row is a real decision, not a technicality: deploys, migrations-the-act (versus migrations-the-conventions), anything irreversible — you want activation to be a human choosing, and lesson 9's closing argument applies. Skill for the checklist, command for the button.

The anti-patterns, from the field: the junk-drawer skill ("our backend practices" — fires constantly, mostly irrelevant; split it into real situations); the stale skill (the procedure changed, the skill didn't, and the model now confidently follows last quarter's process — same-PR maintenance, lesson 8, applies with extra force because nobody re-reads skills that still fire); and the skill that duplicates the model's competence (packaging generic best practices the model already knows — a skill earns its place by encoding what's yours: your constraints, your conventions, your hard-won exceptions).

Trust: instructions that activate themselves

A skill is text your model will follow autonomously, on a trigger you've delegated to the model itself. For your own skills, that's the point. For third-party skills, read what you're installing — the way you'd skim a shell script before piping it to bash. Two specific cautions: the description you're trusting is precisely the mechanism that decides when it speaks into your sessions; and the body will be followed with the same weight as your own instructions. Lesson 26 covers what hostile versions look like; the prevention here is boring and effective — read before installing, prefer sources you'd take a dependency from, and diff on update.

Step back and see the progression you've completed: prompt (say it once) → command (save it, human invokes) → skill (save it, situation invokes). Each step moves knowledge further from your working memory into the environment — and the environment, unlike you, doesn't have a busy Friday. What remains is the general question — of everything you could keep resident versus load on demand, what should be where? — and that's lesson 20, where the answer becomes arithmetic.