Claude Code Skills
Everything about Claude Code skills in one place: what a SKILL.md is,
the full frontmatter reference, every bundled skill, where skills live, dynamic context injection,
and copy-paste examples. Verified against the official Anthropic docs.
What is a Claude Code skill?
The one-paragraph answer, then the details.
A Claude Code skill is a SKILL.md file — YAML frontmatter plus
markdown instructions — stored in a .claude/skills/<name>/ folder. Claude loads it
automatically when your request matches the skill's description, or you run it
directly with /skill-name. Unlike CLAUDE.md, a skill's body loads
only when it is used, so long reference material costs almost nothing in context until you need it.
Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a
section of your CLAUDE.md has grown from a fact into a procedure. Claude Code skills follow the open
↗ Agent Skills
standard, so the same SKILL.md works across multiple AI tools, and Claude Code adds extras on top:
invocation control, subagent execution, and dynamic context injection.
.claude/commands/deploy.md and a skill at
.claude/skills/deploy/SKILL.md both create /deploy. Your existing
.claude/commands/ files keep working — skills just add supporting files, frontmatter, and auto-loading.
Skill vs command vs subagent vs MCP
Four things people mix up. Here is the clean line between them.
| Building block | What it is | Reach for it when |
|---|---|---|
| Skill | Reusable instructions in SKILL.md, loaded on demand | You repeat the same procedure or reference and want Claude to apply it automatically |
| Slash command | The same thing — commands merged into skills | You want a manual /trigger; add frontmatter to upgrade it into a full skill |
| Subagent | A separate context window that does a side-task and reports back | You want focused work done without spending your main context |
| MCP server | An external tool/data connector (GitHub, Postgres, Playwright) | You need Claude to reach a system outside the repo |
They compose: a skill can be set to run in a subagent, and its instructions can tell Claude to call an MCP tool. See subagents and MCP in the main guide.
Where skills live
The folder you choose decides who can use the skill.
| Scope | Path | Applies to |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | All your projects |
| Project | .claude/skills/<name>/SKILL.md | This project only (commit it to share with the team) |
| Plugin | <plugin>/skills/<name>/SKILL.md | Wherever the plugin is enabled (namespaced plugin:skill) |
| Enterprise | Managed settings | All users in your organization |
.claude/skills/ (e.g. apps/web/.claude/skills/deploy) loads the first time
Claude touches a file in that directory and shows up as /apps/web:deploy, so a package can ship its own skills.
Bundled skills
Skills that ship with Claude Code — available in every session.
Bundled skills are prompt-based: they hand Claude a detailed procedure and let it orchestrate the work with its tools. You invoke them with a slash, the same as any skill.
| Skill | What it does |
|---|---|
/doctor | Setup checkup for your Claude Code install |
/code-review | Structured review of your changes. Runs only when you invoke it (v2.1.215+) |
/debug | Structured debugging of a failing behavior |
/batch | Parallel work across git worktrees |
/loop | Repeat a prompt on an interval |
/claude-api | Auto-loads the Claude API reference when your code imports the Anthropic SDK |
/run | v2.1.145+. Launch and drive your app to see a change working |
/verify | v2.1.145+. Build and run the app to confirm a change works. Invoke-only (v2.1.215+) |
/run-skill-generator | v2.1.145+. Records how to build and launch your project so /run and /verify stop guessing |
/doctor) with the disableBundledSkills setting.
You can also shadow any bundled skill by creating your own skill with the same name — a project code-review replaces the bundled /code-review.
Create your first skill
A real, useful skill in two files. Copy, paste, done.
This skill summarizes your uncommitted changes and flags anything risky. It pulls the live diff into the prompt
before Claude reads it, so the answer is grounded in your actual working tree. Claude loads it when you ask what changed,
or you invoke it with /summarize-changes.
Step 1 — make the folder (personal, so it works in every project):
mkdir -p ~/.claude/skills/summarize-changesStep 2 — write the skill:
---
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.
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above 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.
The !`git diff HEAD` line is dynamic context injection: Claude Code runs the command and replaces the
line with its output before Claude sees the skill, so the instructions arrive with your real diff already inlined. Open a project,
make an edit, and ask "what did I change?" — or type /summarize-changes.
SKILL.md.
SKILL.md frontmatter reference
Every field is optional. Only description is recommended.
| Field | What it does |
|---|---|
name | Display name in skill listings. Defaults to the directory name (which is also the command you type) |
description | What the skill does and when to use it — Claude reads this to decide when to auto-load. Put the key use case first (capped at ~1,536 chars with when_to_use) |
when_to_use | Extra trigger context: example requests or phrases. Appended to description |
disable-model-invocation | Set true so Claude never auto-runs it — manual /name only. Ideal for deploys |
user-invocable | Set false to hide it from the / menu (background knowledge only) |
allowed-tools | Tools pre-approved without a permission prompt for the invoking turn |
disallowed-tools | Tools removed from the pool while the skill is active |
model | Model override while the skill is active (or inherit) |
effort | Effort level while active: low / medium / high / xhigh / max |
context | Set fork to run the skill in its own subagent context |
agent | Which subagent type to use when context: fork is set |
background | With fork, set false to wait for the result in the same turn (v2.1.218+) |
argument-hint | Autocomplete hint for expected arguments, e.g. [issue-number] |
arguments | Named positional args for $name substitution in the body |
hooks | Hooks scoped to this skill's lifecycle |
paths | Glob patterns that limit when the skill auto-activates |
shell | bash (default) or powershell for inline !`command` blocks |
Dynamic context & arguments
Feed live data and user input into a skill.
Command injection runs a shell command and inlines its output before Claude reads the skill. Wrap a command in
!`…` anywhere in the body:
## Open pull requests
!`gh pr list --limit 20`
## Instructions
Group the PRs above by author and flag any open longer than a week.Argument substitution passes what the user typed after the command into the body:
| Placeholder | Expands to |
|---|---|
$ARGUMENTS | Everything passed after the command name |
$0, $1… | A single argument by position (shorthand for $ARGUMENTS[N]) |
$name | A named argument declared in the arguments frontmatter list |
${CLAUDE_SKILL_DIR} | The skill's own folder — use it to call a bundled script from anywhere |
${CLAUDE_PROJECT_DIR} | The project root |
${CLAUDE_SESSION_ID} | The current session ID (logging, session-specific files) |
Run a skill in a subagent
Keep heavy or noisy work out of your main context.
Add context: fork and the skill runs in its own subagent with a fresh context window. Pair it with
disable-model-invocation: true for workflows you always trigger by hand, agent to pick the subagent type,
and background: false when you want the result back in the same turn.
---
name: deploy
description: Deploy the application to production
context: fork
disable-model-invocation: true
---
Deploy the application:
1. Run the test suite
2. Build the application
3. Push to the deployment targetPopular skills & where to find more
Battle-tested skills, and the directories worth bookmarking.
Browse the ecosystem
Claude Code Skills FAQ
Quick answers to the questions people actually search.
SKILL.md file (YAML frontmatter plus markdown instructions) in a .claude/skills/<name>/ folder. Claude loads it automatically when your request matches the description, or you run it directly with /skill-name. Its body loads only when used, so it costs almost no context until you need it..claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. Skills add a folder for supporting files, frontmatter to control invocation, and automatic loading when relevant.~/.claude/skills/<name>/SKILL.md (all your projects); project skills go in .claude/skills/<name>/SKILL.md (that repo only, commit to share). Enterprise and plugin skills are also supported. On a name clash, enterprise beats personal beats project, and any of them beats a bundled skill of the same name./doctor, /code-review, /batch, /debug, /loop, and /claude-api, plus the run-and-verify trio /run, /verify, and /run-skill-generator (v2.1.145+). As of v2.1.215, /verify and /code-review run only when you invoke them.disable-model-invocation: true to the frontmatter. Claude won't load it automatically; it runs only when you type /skill-name. Use it for deploys, releases, and other actions you want to trigger by hand.context: fork and the skill runs in a forked subagent with its own context window. Use agent to pick the subagent type and background: false to wait for the result in the same turn.