Skills: teaching Claude Code your team's playbook

Every team runs on procedures that live in someone's head: how we cut a release, what a proper migration looks like, the seven checks before a schema change merges. With Claude Code you have three bad options: re-explain it every session, paste it from a stale wiki, or bloat CLAUDE.md with text you need twice a month. And one good one: package it as a skill.

A skill is a folder holding a SKILL.md: YAML frontmatter with a name and description, then the procedure itself in plain markdown. It can bundle supporting files (scripts, templates, reference docs) that the agent reads or runs when the skill is active. Project skills live in .claude/skills/, personal ones in ~/.claude/skills/, and any of them can be invoked explicitly as a slash command or picked up by the model when a task matches.

Progressive disclosure is the whole trick

What makes skills different from more markdown lying around: at session start, only the frontmatter loads, a name and one description sentence per skill. The body, your actual playbook, enters context only when the skill fires. CLAUDE.md charges you every turn; a skill charges you a sentence until the moment it is needed.

That inverts the economics of writing things down. A four-page release runbook in CLAUDE.md would be malpractice; as a skill it is nearly free. The catch: the description becomes the routing layer. The model decides whether to load your skill by reading that one sentence. "Helps with testing" fires never or always; "use when cutting a release: version bump, changelog, tag, publish checklist" routes precisely. Write descriptions the way you write API contracts. This is prompt-as-code in the most literal sense: versioned, reviewed, shipped with the repo.

A skill is a prompt with a loading strategy: one sentence always resident, the full playbook only when it earns its way into context.

Good skill, bloated skill

The good ones I have written share a shape: one procedure, imperative steps, exact commands, a verification step at the end, and the two edge cases that actually bite. A checklist you would hand a capable mid-level engineer. The bloated ones share a shape too: a whole manual pasted into SKILL.md, five procedures under one vague name, no way to tell whether it worked, and a description so broad it competes with every other skill on every task. Once skills multiply across a team, that competition turns into a real coordination problem. Governing skills at scale is its own discipline, worth reading before you have twenty of them.

Skills, hooks, or CLAUDE.md

Skills sit in a triangle with the other two steering mechanisms, and picking wrong wastes either context or reliability.

• CLAUDE.md for always-true facts and conventions: short, resident on every turn. What belongs there is its own question.
• Hooks for anything that must happen without fail: formatters, blockers, notifications. If skipping it is never acceptable, make it a hook, not prose.
• Skills for on-demand procedures: multi-step, occasional, too long to keep resident.

The honest limitation: automatic triggering is probabilistic. The model may not load your skill when you would have, especially once descriptions overlap; the slash command is the reliable path, auto-invocation the convenient one. Test in fresh sessions by asking for the task and watching whether it fires. And prune. Stale skills rot exactly like stale wikis, just more quietly, because a skill that stopped matching never complains.

Start with the last procedure you explained twice in one week. Write it as steps, keep it under a page, give it a description you would bet on, check it in. If a month later your teammates' sessions invoke it without anyone thinking about it, you have packaged a small piece of the team's judgment. That is the actual promise here, more than most AI tooling can honestly claim.