CONCEPT A skill is a folder with a SKILL.md
An Agent Skill is a directory whose entrypoint is a single file called
SKILL.md. That file has two parts: YAML frontmatter between ---
markers, and a markdown body of instructions. The frontmatter carries a
name and a description; the body is the procedural knowledge Claude follows once the
skill is in use. Alongside SKILL.md the folder may bundle optional supporting files
— reference docs, templates, example outputs, and executable scripts.
SKILL.md. Everything else (scripts,
references, assets) is optional and loaded only when needed.Claude Code skills follow the Agent Skills open standard (agentskills.io), so the same folder
format works across Claude products — Claude Code, the Claude API, and claude.ai — though each surface manages
and stores skills differently. Create a skill "when you keep pasting the same instructions, checklist, or
multi-step procedure into chat," or when a section of CLAUDE.md has grown from a fact into a
procedure. Unlike CLAUDE.md — which is always in context — a skill's body loads only when it's
used, so long reference material costs almost nothing until you need it.
CONCEPT Model-invoked, not user-invoked
The defining trait of a skill is that it is model-invoked: Claude decides to use one
by matching your request against the skill's description. You don't have to name it. Ask
"what did I change?" and Claude loads a summarize-changes skill on its own if the description says
so. This contrasts with a classic slash command, which is user-invoked — nothing happens until
you type it. In Claude Code a skill is both by default: Claude can auto-trigger it, and you can also run
it directly by typing /skill-name (the command name comes from the directory name).
| Aspect | Agent Skill |
|---|---|
| What it is | A folder with SKILL.md + optional bundled files |
| Required frontmatter | name and description (only description is truly recommended) |
| Who triggers it | Claude, by matching the task to the description (also user-typable as /name) |
| When the body loads | Only when the skill triggers — not upfront |
| Standard | Agent Skills open standard (agentskills.io) |
.claude/skills/ to your repo and the whole team gets the capability.DIAGRAM Anatomy of a skill folder
a skill's description?"} M -->|"yes"| LOAD["🟢 Claude loads SKILL.md body
(model-invoked)"] M -->|"or you type /name"| LOAD LOAD --> B["Body: markdown instructions"] B --> OPT{"Body references
bundled files?"} OPT -->|"reference.md / examples.md"| REF["📄 Read as needed"] OPT -->|"scripts/helper.py"| SCR["⚙️ Execute via bash
(code never enters context)"] M -->|"no match, not typed"| SKIP["⚪ Only name+description
stay in context"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class LOAD ok; class REF gate; class SCR gate; class SKIP bad;
CODE A minimal SKILL.md
The directory name (summarize-changes) becomes the command /summarize-changes. The
description tells Claude what the skill does and when to use it — that string is
what auto-invocation matches against.
# File: ~/.claude/skills/summarize-changes/SKILL.md
---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the
user asks what changed, wants a commit message, or asks to review their diff.
---
## Instructions
Summarize the current git diff in two or three bullet points, then list any risks
you notice such as missing error handling, hardcoded values, or tests that need
updating. If the diff is empty, say there are no uncommitted changes.
name ≤ 64 chars, lowercase letters, numbers,
and hyphens only, and cannot contain the reserved words anthropic or claude.
description must be non-empty and ≤ 1024 chars.TRADE-OFFS Skill vs. stuffing it all into CLAUDE.md
✅ Put a procedure in a skill
- Body loads only when the task matches — near-zero idle cost
- Can bundle scripts and reference files
- Directly invocable as
/name - Reviewable, versioned, shareable per-folder
⚠️ Put the same procedure in CLAUDE.md
- Always in context — pays tokens every turn, used or not
- No bundled files, no scripts
- Grows unwieldy as procedures pile up
- Good only for short, always-true facts
EXAM TRAPS
SKILL.md. The folder can also hold scripts, references, and assets.description. You can
also type /name, but auto-invocation is the point.name." → Only description is recommended;
name is optional and defaults to the directory name. But you can't skip the SKILL.md
file itself.PRACTICE
Q1 · What are the two required-ish pieces of a skill's frontmatter, and which matters most?
name and description. Only description is genuinely recommended — it's what Claude matches the task against to decide whether to auto-invoke. name is optional and defaults to the folder name.
Q2 · Why is "model-invoked" the key property of a skill?
Because Claude decides to load the skill on its own by matching your request to the
description, without you naming it. That's the contrast with a plain slash command, which does
nothing until the user types it. A skill can still be typed as /name, but auto-invocation is what
makes it a skill.
Q3 · When should a procedure live in a skill rather than in CLAUDE.md?
When it's a task-triggered procedure (a checklist, a multi-step workflow) rather than an always-true fact. CLAUDE.md is always in context and pays tokens every turn; a skill's body loads only when the task matches, so long procedures cost almost nothing until used.