Explainer
What are Claude skills?
A skill is a folder with a SKILL.md file that teaches an AI agent one job: the frontmatter says what it is and when to use it, the body says how to do it. This page covers the file, the trigger, the install and how to write one.
The short answer
A skill is a folder containing a SKILL.md file. The file has two parts:
---
name: pdf
description: Read, split, merge and fill PDF files. Use when a task involves PDF documents.
---
# PDF
Steps the agent should follow, checks to run, examples…
- The frontmatter (
name,description) is metadata. The description is the trigger. - The body is the procedure: what to do, in what order, with which checks.
- Optional scripts and assets can sit next to the file and be called from it.
Agents that support skills — Claude Code, Codex, Cursor and others — load them on demand, not all at once. That is the point: a skill costs nothing until your request matches its description.
How the agent decides to load a skill
The agent compares your request to the description field. If the vocabulary matches, the skill is loaded into context; if not, it stays on disk.
This is why two failure modes dominate:
- The description is vague (“a helpful skill for documents”), so it never matches — see SKILL.md errors.
- The description is precise, but you asked for something adjacent, so a different skill wins.
Practical consequence: when you install a skill, read its description and use its vocabulary in your request. “Make me a PDF with a form” triggers a PDF skill; “make a document” may not.
Where skills live
| Scope | Path | Use it for |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md |
Skills you want in every project |
| Project | <project>/.claude/skills/<name>/SKILL.md |
Skills that only make sense in one repo |
Other agents use their own skills folder; the CLI writes to the right one for the agent you target.
How to install one
npx skills add <owner>/<repo> --skill <name>
For example npx skills add anthropics/skills --skill pdf. To target one agent explicitly, add -a claude-code (or -a cursor, -a codex). Full walkthrough: how to install Claude skills.
How to create your own
- Pick one job. A skill that does three things triggers for none of them.
- Write the frontmatter. Kebab-case
name, and adescriptionthat states the job and the cue: “Use when the user asks to …”. - Write the body as a procedure. Steps, order, checks, one worked example. No marketing copy.
- Add scripts only if needed, and reference them with paths relative to the skill folder.
- Test the trigger. Ask the agent a task that should match, and one that should not. If the wrong one triggers, fix the description first.
Check the structure with the SKILL.md validator before you publish.
Skill vs MCP server vs subagent
| Mechanism | What it gives the agent | When it loads |
|---|---|---|
| Skill | A method: steps and checks | On demand, when the description matches |
| MCP server | Connectivity: tools and data | Connected at session start |
| Subagent | Isolation: its own context and tools | When delegated |
| Slash command | A prompt you invoke | Only when you type it |
If the agent needs access, use MCP. If it needs a method, write a skill. The full comparison is in skills vs agents, plugins and MCP.
Frequently asked
Do skills work in every AI tool? No. Claude Code, Codex and Cursor support the format; other tools may not. The file is plain Markdown, so portability is high, but support is not universal.
Do skills cost tokens when idle? The file sits on disk. It enters context when the agent loads it, which is why precise descriptions matter.
Can a skill run code? Yes — the body can tell the agent to run scripts that ship with the skill. That is exactly why you should read the file first.
Community notes
Found a broken install? Know a skill we missed?
One line is enough: the skill name, what happened, and the command you ran. We read every note and fix the index.