primer
What is a Claude skill, and why does yours never trigger?
A skill is a folder with a SKILL.md file that Claude opens only when the description matches your request. That single sentence explains most of what goes wrong.
A skill is a folder, not a plugin
Strip the marketing off and a skill is this: a directory with one SKILL.md file in it. Nothing compiles, nothing runs as a service, there is no server to host. Claude reads the front matter, decides whether the skill is relevant to what you just asked, and if it is, opens the instructions and follows them.
my-skill/
└── SKILL.md
That is the whole minimum. Bigger skills add scripts/, references/ and assets next to it — the document skills inside anthropics/skills ship scripts that build and inspect real .docx and .pptx files.
What goes inside SKILL.md
---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---
# My Skill Name
[instructions Claude follows when this skill is active]
## Examples
- Example usage 1
## Guidelines
- Guideline 1
Two front-matter fields are required: name (lowercase, hyphens for spaces) and description. The description is not decoration — it is the matching surface. Claude chooses from it, so "helps with code" loses to "reviews a git diff for correctness, naming and missing tests".
How triggering actually works
Three consequences worth internalising:
- Vague asks skip skills. "Make this better" matches nothing. "Review my working tree before I commit" matches a review skill, because that is how the skill describes itself.
- Naming it is allowed. You can say "use the code-review skill on this diff" and it loads regardless of phrasing.
- Install scope is not global by default. A skill added in one project's agent does not automatically appear in another tool. When something seems broken, check it is installed where you are actually working before blaming the skill.
Skill, MCP server, plugin
| Thing | What it is | What it is good for |
|---|---|---|
| Skill | A folder of instructions and resources | Teaching a repeatable workflow, house style, checklists |
| MCP server | A connection exposing tools and data | Letting the agent reach a database, an API, a browser |
| Plugin | A package that can bundle skills, commands, MCP config | Installing a whole setup in one move |
They stack. You use an MCP server so the agent can reach your CMS, a skill so it knows your publishing checklist, and a plugin to ship both to a teammate.
Where skills come from
- Bundled in Claude — document skills (docx, pdf, pptx, xlsx) on paid plans.
anthropics/skills— Anthropic's public examples; addable as a Claude Code plugin marketplace with/plugin marketplace add anthropics/skills.- The open ecosystem — install with
npx skills add <repo> --skill <name>, which is how everything on the main list is installed. - Your own — the ten-minute version above. If you want the agent to help write it, install
skill-creator.
The mistake everyone makes first
Installing twenty skills. Each one costs context when it loads and adds another description the model has to weigh, so a bloated set makes triggering worse, not better. Install find-skills, then add one skill per real repeatable task — a review skill, the design skill for the stack you actually use, and nothing else until you feel the gap.