Short answer: a skill is a folder containing a SKILL.md file: a name, a one-line description, and instructions for one job, such as writing release notes or reviewing a migration. Put it in ~/.claude/skills/<name>/ for yourself or .claude/skills/<name>/ for a project. Claude reads only the descriptions up front and loads a skill's instructions when a request matches.
I started with everything in CLAUDE.md. It grew to 300 lines, most of which had nothing to do with what I was asking. Moving the job-specific parts into skills made both better.
What goes in a SKILL.md?
A block of front matter, then plain Markdown:
---
name: release-notes
description: Write release notes from the commits since the last tag. Use when the user asks for release notes, a changelog entry or "what changed".
---
# Release notes
1. Find the last tag with `git describe --tags --abbrev=0`.
2. List the commits since then and group them: added, changed, fixed.
3. Write each line for a user, not a developer: what they can now do.
4. Leave out refactors, test changes and dependency bumps.The folder can hold more: a template, a script the instructions run, a reference file that is only read when needed. The instructions point to them by relative path.
Why does the description matter so much?
At the start of a session Claude sees each skill's name and description, not its body. It decides whether to open a skill by matching your request against that description. So the description has to say two things: what the skill does and when to use it, in the words people actually use.
"Release notes helper" will rarely fire. "Write release notes from the commits since the last tag. Use when the user asks for release notes, a changelog entry or what changed" will.
When a skill never seems to be used, the description is almost always the reason.
Where do skills live?
| Folder | Who has it |
|---|---|
~/.claude/skills/<name>/SKILL.md | You, in every project |
.claude/skills/<name>/SKILL.md | Everyone who works in the project (commit it) |
Plugins can bring skills too. You can also ask for one directly by name instead of waiting for Claude to pick it.
Skill or CLAUDE.md?
- CLAUDE.md is read in full at the start of every session. Put there what is true for every task: how to run the tests, the conventions, what never to do.
- A skill is loaded only when its job comes up. Put there anything long that only matters for one kind of task.
A useful test: if a paragraph in CLAUDE.md starts with "When you are asked to...", it probably wants to be a skill.
Where can you check this?
How long should a skill be?
As long as the job needs and no longer. Under 500 lines for the SKILL.md itself is a good ceiling; move long references into separate files in the folder, which are read only when the instructions point to them. More on keeping CLAUDE.md lean in What to put in CLAUDE.md.
Config Studio for Claude Code lists skills with CLAUDE.md, commands, agents and the rest of its 20 surfaces, shows every file each one can live in and which one wins, and writes the file beside the options you pick.
