Claude Code skills: how to write ones that actually fire

A skill is a folder with a SKILL.md file in it: a short description that tells Claude when to use it, and instructions Claude loads only when that moment comes. Use a skill for any procedure you have explained more than twice — a release routine, a review checklist, a research method. Keep CLAUDE.md for the facts every session needs. The description is the part that decides whether the skill ever runs, so write it first and write it carefully.

Where skills live

Path	Who gets it
`~/.claude/skills/<name>/SKILL.md`	you, in every project on this machine
`.claude/skills/<name>/SKILL.md`	everyone who works in this repository (commit it)
`<plugin>/skills/<name>/SKILL.md`	wherever the plugin is enabled, as /plugin:name

You can run any skill yourself by typing / and its name at the start of a message. Older custom slash commands in .claude/commands/ still work; skills are the same idea with a folder for supporting files and the option for Claude to load them on its own.

What goes in SKILL.md

---
name: release-notes
description: Use when the user asks for release notes, a changelog entry or
  "what shipped this week". Reads merged PRs and writes notes in our house style.
---

1. List PRs merged since the last tag: run ${CLAUDE_SKILL_DIR}/scripts/merged.sh
2. Group them by user-facing change, not by file.
3. Follow style.md in this folder. Never mention internal ticket numbers.

Frontmatter. Every field is optional, but description is the one that matters: it is all Claude sees until the skill is used. Other fields can stop Claude from invoking the skill on its own, pre-approve the tools it needs, or run it in a separate subagent context.
The body. Steps, in the order you would give them to a new colleague. Anthropic suggests keeping it under 500 lines and moving reference material into other files in the folder, linked from the body, so it loads only when needed.
Scripts. Anything deterministic — a query, a conversion, a check — belongs in a script inside the folder, which Claude runs rather than reads. Refer to it through ${CLAUDE_SKILL_DIR}, the skill’s own directory, so it works from whatever folder the session is in. This is where we put every calculation: the model decides what to run, code does the arithmetic.

The description is the trigger

At the start of a session Claude sees only each skill’s name and description; the body stays on disk until a request matches. That makes the description a routing rule, and most skills that “never fire” have a description written as a title (“Release notes helper”) instead of a condition. What works for us:

Start with “Use when…” and the situation, not the feature.
Include the words people actually type: “what shipped”, “changelog”, “wrap up”.
Put the main use case first. The listing cuts each description off at 1,536 characters.
Say when not to use it if a neighbouring skill overlaps.

Skill, rule, subagent or tool?

Use	When
A line in `CLAUDE.md`	Every session needs it: how to run the tests, where things live, a standing rule.
A skill	A procedure needed some of the time, with steps, files or scripts that would bloat `CLAUDE.md`.
A subagent	Work whose reading is large and whose answer is small, done in a separate context.
An MCP tool	Claude needs a capability it lacks: another system’s data or actions.
A hook	A rule that must never be broken. Hooks run as code; skills and rules are instructions.

The pairs get confused because they overlap. A skill can call an MCP tool and can run itself in a subagent; a subagent definition can preload skills (see our guide to subagents). The test we use: is this knowledge (a rule or a skill), a place to work (a subagent), a capability (a tool), or a guarantee (a hook)?

What we learned running them daily

Fewer is better. Every installed skill’s description sits in context and competes for the same decision. Past a few dozen, the right one fires less often. We prune regularly, the same way we keep subagent definitions short — Claude Code warns at startup once custom agent descriptions pass 15,000 tokens.
Discipline beats features. The skills that earn their place enforce habits — verify before claiming done, write the test first, debug from evidence — more than they add tricks.
Skills survive long sessions, within a budget. When a long conversation is compacted, Claude Code re-attaches recently used skills, keeping up to 5,000 tokens of each and 25,000 in total. Another reason to keep the body short and put the detail in files.
Version them. Project skills live in the repository, so they get reviewed and improved like code, and a new colleague gets them on their first clone.

What we checked

Read 2026-11-01 from Anthropic's skills documentation and the subagents documentation.

Getting it set up

Skills are one of five things that make Claude Code useful; our free guide to setting up Claude Code properly covers the other four. AI Setup includes writing your first skills with you, from procedures you already run.