The problem skills solve
You have explained your deploy procedure to the agent three times this week. You could put it in the project's instruction file — but that file is read on every task, and most tasks are not deploys. Ten procedures later the file is enormous and the agent is paying attention to none of it.
A skill fixes this with one idea: load on demand. The agent always sees a one-line description of each skill. Only when a task matches does it read the full instructions. You can have fifty skills installed and pay for one.
What a skill is
A folder with a file called SKILL.md. The top of the file has a name and a description; the rest is instructions in plain Markdown. Scripts and reference files can sit alongside it.
release-notes/
├── SKILL.md
└── collect-commits.sh---
name: release-notes
description: Write release notes for this project. Use when the
user asks for release notes, a changelog entry, or "what
changed since the last release".
---
# Writing release notes
Run ./collect-commits.sh to list commits since the last tag.
Group the changes under Features, Fixes, and Other. Write each
line for a customer, not a developer: say what they can now do,
not which function changed. Leave out refactors and typo fixes.
Prepend the result to CHANGELOG.md under a heading with today's
date. Show the user the new section before saving.In Claude Code, a project's skills live in .claude/skills/ (shared with the team through the repository) and your personal ones in ~/.claude/skills/. Other agent tools have adopted the same folder format.
Writing a good one
- The description is the trigger. It is all the agent sees when deciding whether to load the skill. Say what the skill does and when to use it, in the words a user would actually type.
- Write what the agent doesn't already know. It knows how to write Markdown and use git. It doesn't know that your notes are customer-facing or where your changelog lives. Every line should be something specific to you.
- Explain the goal, not just the steps. As in Prompting: a reason lets the agent handle the case you didn't write down.
- Put fixed logic in a script. If a step must be done exactly the same way every time, write it as a script and have the skill run it. Code is reliable; prose is a suggestion.
- Keep big references in separate files. Link to them from
SKILL.md; the agent reads them only if it needs to.
Skills, instruction files, MCP — which one?
| Use | For | Loaded |
|---|---|---|
| Instruction file (CLAUDE.md) | Facts true for every task in the project | Always |
| Skill | How to do one kind of task | When the task matches |
| MCP server | Access to a system — a database, an API, a service | Its tools are always offered |
The short version: MCP gives an agent hands; skills give it know-how. They combine well — a skill that describes how to triage a bug report, using an MCP server that can read your ticket system. Building an MCP server comes later, in MCP Servers.
Try it
Pick the thing you explained to an agent most recently. Write it down as a SKILL.md — ten lines is plenty. Then start a fresh session, ask for that task without explaining it, and see whether the agent picks the skill up. If it doesn't, the description is what to fix.