Claude Code skills: when a skill beats a rule.

Claude Code gives you three places to put guidance: CLAUDE.md rules, skills and hooks. They differ in when they cost context and how firmly they apply. Choosing the right one keeps the always-loaded file small.

How a skill loads

A skill is a folder with a SKILL.md, kept in ~/.claude/skills/ for all your projects or .claude/skills/ in a repository. At session start Claude sees only each skill's name and description. The full body loads when the skill is invoked, either because you type /skill-name or because Claude judges the description matches your request. Supporting files in the folder load only when the skill points at them. A rule in CLAUDE.md, by contrast, is paid for on every turn of every session.

What goes where

A rule when it is short and applies to nearly every session: how to report results, the verify command, the commit style.
A skill when it is a procedure or reference you need only for some tasks: release steps, a migration recipe, a code review checklist, a long how-to for an internal tool.
A hook when it must hold even if the model forgets: no force push, no edits to a protected folder. Rules and skills ask; hooks enforce.

A skill that earns its place

The description is what makes Claude pick it, so put the trigger there, and keep the body to steps the agent can follow.

---
name: release
description: Cut a release of this repo. Use when the user asks to release, tag or publish a version.
---

# Release

1. Run npm run verify. Stop if it fails.
2. Bump the version in package.json and add the changelog entry.
3. Tag with v<version> and push the tag.
4. Report the tag and the verify result.

Details for the changelog format: see changelog-format.md in this folder.

Useful frontmatter, per the Claude Code docs: disable-model-invocation: true keeps a skill manual-only, which suits anything with side effects such as a deploy, and allowed-tools lets the skill use named tools without prompting while it runs. Keep SKILL.md under about 500 lines and move detail into files it references.

Moving a procedure out of CLAUDE.md

Take the release checklist that has sat in CLAUDE.md for months. Cut it, create the skill above, and leave nothing behind: the description already tells Claude when it applies. If you want a visible pointer, one line is enough ("release steps: the release skill"). The footprint drops by the whole checklist, and the steps still load at the moment they are needed.

Watch for these

A vague description never fires. "Helpful release tools" matches nothing. Name the task and the words a user would say.
Skills are not enforcement. Claude chooses whether to use one. If a step must happen, back it with a hook or a verify command.
Invoked skills stay in context. After compaction the start of each is kept within a size cap, so put the most important lines first.

The CommonRig kit ships its protocols as skills of this shape (for example build-and-verify, storage-hygiene and session-close-out), with the rule kernel pointing at them instead of repeating them. The footprint score counts how many SKILL.md files you have but does not count their contents, since they only load on demand. For the size side, see measuring context cost.

Check your own files

Paste your CLAUDE.md or AGENTS.md into the free footprint scorer, or get the free sample and run rig doctor --lite locally. The hosted doctor check is A$0.50 a run and scores the whole setup, hooks included. The kit (A$10 once) has the rule source, generator, hooks and protocols these guides describe.