Reusable playbooks Claude discovers
A skill is a folder of instructions and resources that teaches Claude Code how to do a specific kind of work. Each lives in a SKILL.md file with a name and description in its frontmatter, and below that the actual instructions (a checklist, formatting rules, whatever the task needs).
Key concept · The description drives matching; skills load on demand
The description is how Claude decides whether to use a skill — it compares your request against every skill's description and activates the ones that match, automatically (you can also invoke one explicitly). Skills load on demand: only the name and description sit in context until a match, so they don't clog the window. Where they live: personal skills in ~/.claude/skills follow you across projects; project skills in .claude/skills are committed to the repo and shared with anyone who clones it.
Metadata, descriptions, and multi-file skills
A basic skill needs only name and description; advanced fields and structure make it more powerful.
Key concept · Fields, allowed-tools, and progressive disclosure
Frontmatter fields: name (required, lowercase/hyphens, ≤64 chars), description (required, ≤1,024 chars — answer what it does and when to use it; add keywords that match how you phrase requests), allowed-tools (optional — restrict what Claude can do when the skill is active, e.g. Read, Grep, Glob for a read-only skill), and model (optional). For bigger skills, use progressive disclosure: keep SKILL.md under ~500 lines and link to supporting files Claude reads only when needed — organized as scripts/, references/, and assets/. Crucially, scripts run without loading their contents into context — only the output costs tokens — so tell Claude to run the script, not read it.
Skills vs. other features — and sharing them
Claude Code offers several customization options; picking the wrong one adds complexity. Skills are the automatic, task-specific one.
| Feature | Nature | Best for |
|---|---|---|
| CLAUDE.md | Loads into every conversation | Always-on project standards and constraints |
| Skills | Load on demand when matched | Task-specific expertise you'd otherwise re-explain |
| Subagents | Isolated execution context | Delegated work, different tool access, isolation |
| Hooks | Event-driven (on save, on tool call) | Automated side effects and validation |
| MCP servers | External tools/integrations | Reaching systems and data outside the codebase |
Key concept · Sharing and troubleshooting
Share skills by committing project skills to the repo, bundling them into plugins, or deploying org-wide through managed settings. Troubleshoot a skill that isn't triggering by improving its description — add keywords that match how you actually phrase the request, since the description is what Claude matches against. Don't force everything into skills: combine them with the other features, each doing its specialty.
Chapter 16 quiz
Fourteen questions on skills, configuration, and choosing between features. Answer first, then expand Show answer.
Part A · Multiple choice
What file defines a skill?
- A SKILL.md with name and description in its frontmatter
- B CLAUDE.md
- C package.json
- D README.md
Show answer
A.
How does Claude decide whether to use a skill?
- A It matches your request against each skill's description
- B Alphabetically
- C By file size
- D At random
Show answer
A. The description is the most important field.
Where do personal skills live?
- A ~/.claude/skills
- B .claude/skills in the repo
- C /etc/claude
- D node_modules
Show answer
A. Project skills go in .claude/skills in the repo.
Which two frontmatter fields are required?
- A name and description
- B model and allowed-tools
- C title and author
- D version and license
Show answer
A. allowed-tools and model are optional.
What does allowed-tools do?
- A Restricts which tools Claude can use while the skill is active
- B Adds more tools automatically
- C Sets the price
- D Names the author
Show answer
A. Useful for read-only or security-sensitive skills.
Progressive disclosure means:
- A Keep SKILL.md lean (~under 500 lines) and link to files Claude reads only when needed
- B Reveal the skill slowly to users
- C Cram everything into one file
- D Hide the skill
Show answer
A. Organized as scripts/, references/, assets/.
Why tell Claude to run a script rather than read it?
- A Scripts execute without loading their contents into context — only output costs tokens
- B Reading is faster
- C Scripts can't be read
- D No difference
Show answer
A.
For always-on project standards you'd use:
- A CLAUDE.md
- B A skill
- C A hook
- D A subagent
Show answer
A. Skills are for task-specific, on-demand expertise.
Part B · True or false
Skills load their full contents into every conversation, like CLAUDE.md.
Show answer
False. Only name/description sit in context until a match; then the skill loads.
Project skills committed to a repo are shared with anyone who clones it.
Show answer
True.
If a skill isn't triggering, improving its description with better keywords helps.
Show answer
True. The description is what Claude matches against.
Hooks are request-driven and skills are event-driven.
Show answer
False. Hooks are event-driven; skills are request-driven.
Part C · Short answer
What two questions should a good skill description answer?
Show answer
What does the skill do, and when should Claude use it.
Name three ways to share skills.
Show answer
Commit project skills to a repo, bundle them into a plugin, deploy org-wide via managed settings.