TL;DR
A Claude Code skill is a folder with a SKILL.md file. The frontmatter description tells Claude when to load it; the body is the instructions Claude follows. Claude loads a skill automatically when your request matches the description, or you type /skill-name to run it directly. Skills can ship scripts, templates, and reference docs, inject live shell output into the prompt, and run in an isolated subagent.
One thing that changed in early 2026 and trips up older guides: custom commands were merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and behave the same way. Skills are now the recommended format because they add a folder for supporting files and frontmatter to control invocation. Verified against the official Claude Code skills docs as of June 2026.
Who this is for
Developers who already run claude and want to turn “the same workflow I keep retyping” into “type /<name> and it runs” — or better, into something Claude applies on its own when the context fits. It also covers anyone standardizing code review, security review, or release checks across a team.
When a skill is the right tool
Reach for a skill when:
- You’ve run the same workflow three or more times: security review, pre-release QA, batch metadata edits, test generation.
- A section of your
CLAUDE.mdhas grown into a multi-step procedure rather than a fact. Skill bodies load only when used, so moving the procedure out ofCLAUDE.mdcosts almost no context until it runs. - The workflow needs more than one prompt: reference docs, template scripts, or a step-by-step checklist.
- You want everyone on the team to run one standard instead of each person writing their own prompt.
Skill vs. command vs. hook vs. subagent
These four get conflated. As of June 2026 the lines are:
- skill / command: a documented workflow in
SKILL.md(or a plain.mdunder.claude/commands/). Both produce a/nameand both can be loaded automatically by Claude when the task matches the description. The skill format adds a folder for scripts and templates, plus invocation-control frontmatter. Use the skill format for anything beyond one line of text. - hook: a shell command the harness runs on a lifecycle event (
PreToolUse,PostToolUse,Stop,UserPromptSubmit, and others). Use it for deterministic automation like “run lint after every file write.” A hook always fires; a skill is the model’s choice. - subagent: a task that runs in a separate context window and returns a result. Use it for parallel research or to isolate a long context. Note that a skill can itself fork into a subagent with
context: fork(covered below), so the two compose.
Decision shortcut:
| You want… | Use… |
|---|---|
| Reuse a one-line instruction | .claude/commands/<name>.md |
| Apply a multi-step workflow when this kind of task shows up | skill (SKILL.md) |
| Run prettier automatically after every edit | hook |
| Investigate five files in parallel and summarize | subagent |
What’s unique to skills and commands: Claude can auto-select them from the description, so you don’t have to remember to type /.
Anatomy of a skill
A skill is a directory whose entrypoint is SKILL.md. Everything else is optional:
.claude/skills/
pr-summary/
SKILL.md # required: instructions + frontmatter
template.md # optional: a skeleton for Claude to fill
scripts/
fetch-issues.sh # optional: a script Claude can runThe official guidance is to keep SKILL.md under 500 lines and move long reference material into sibling files that the body links to, so the bulk loads only when needed.
SKILL.md frontmatter reference
Frontmatter sits between --- markers. Every field is optional; only description is recommended. The fields below are current as of June 2026 (Claude Code v2.1+):
| Field | What it does |
|---|---|
description | What the skill does and when to use it. Claude matches your request against this. Put the key use case first. |
when_to_use | Extra trigger phrases or example requests, appended to description in the skill listing. |
name | Display label in listings. Defaults to the directory name; for most layouts it does not change what you type after /. |
disable-model-invocation | true means only you can run it (no auto-trigger). Use for /deploy, /commit, anything with side effects. |
user-invocable | false hides it from the / menu so only Claude can load it. Use for background knowledge. |
allowed-tools | Tools Claude may use without asking while the skill is active, e.g. Bash(git add *) Bash(git commit *). |
argument-hint | Autocomplete hint, e.g. [issue-number]. |
arguments | Named positional args for $name substitution. |
context | Set to fork to run the skill in an isolated subagent. |
agent | Which subagent type to use when context: fork is set (Explore, Plan, general-purpose, or a custom one). |
model / effort | Override the model or effort level while the skill runs. |
paths | Glob patterns that limit when the skill auto-loads, e.g. only when editing src/api/**. |
A minimal SKILL.md:
---
name: ship
description: |
Detect the base branch, run tests, review the diff, bump VERSION,
update CHANGELOG, commit, push, and open a PR. Use when the user
says "ship", "release", or asks to cut a version.
---
# Ship workflow
1. Run `git status` and `git diff` to confirm a clean tree.
2. Run the test suite. If it fails, stop and show the output.
3. ... (steps)Two facts worth pinning down:
descriptionis the index Claude matches against. Only skill names and descriptions load into context at startup (progressive disclosure); the body loads when the skill is invoked. The combineddescription+when_to_usetext is capped at 1,536 characters in the listing, so lead with the key use case.- The body stays in context for the rest of the session once invoked. Write standing instructions, not one-time steps, and keep it tight — every line is a recurring token cost.
Where skills live (and who wins on a name clash)
Skills load from four scopes. The priority order is the opposite of what some older guides claim — enterprise overrides personal, personal overrides project:
| Scope | Path | Applies to |
|---|---|---|
| Enterprise | Managed settings | Everyone in the org |
| Personal | ~/.claude/skills/<name>/SKILL.md | All your projects |
| Project | .claude/skills/<name>/SKILL.md | This repo only |
| Plugin | <plugin>/skills/<name>/SKILL.md | Wherever the plugin is enabled |
Plugin skills are namespaced plugin-name:skill-name, so they never collide with the other scopes. Project skills also load from .claude/skills/ in every parent directory up to the repo root, which makes monorepos work: start Claude in a subpackage and it still sees skills defined at the root.
Live change detection covers SKILL.md text edits within the running session — no restart needed — but creating a brand-new top-level skills directory that didn’t exist at startup requires restarting Claude Code so the new path gets watched.
Bundled skills you already have
Claude Code ships prompt-based skills available in every session. As of June 2026 these include:
| Skill | What it does |
|---|---|
/code-review | Review the current diff for bugs and smells |
/security-review | Security review of the current branch |
/debug | Systematic debugging with root-cause investigation |
/run | Launch and drive your app to see a change working |
/verify | Build and run the app to confirm a change does what it should |
/run-skill-generator | Records how to build/launch your project so /run and /verify stop guessing |
/batch | Run a workflow across many items |
/loop | Run a command on a recurring interval |
/claude-api | Write Anthropic SDK code and migrate between model versions |
/run, /verify, and /run-skill-generator need Claude Code v2.1.145 or later. A handful of built-ins are also reachable by the model through the Skill tool, including /init, /review, and /security-review; others like /compact are not. Not sure what’s loaded? Type / for the menu or ask “What skills are available?”
Three ways to invoke a skill
- Direct
/<name>— type/, pick from the menu, press Enter. Most explicit. - Automatic — when your wording matches a skill’s
description, Claude loads it. “Audit the security risks in this PR” can auto-triggersecurity-review. - By reference — say “use the security-review skill on this branch.” More reliable than vaguely asking “check for security issues.”
Arguments come after the name and land in $ARGUMENTS (or $0, $1, … by position):
/fix-issue 123
/loop 5m /verifyIf a skill omits $ARGUMENTS but you pass some, Claude Code appends ARGUMENTS: <your input> so the model still sees what you typed.
Writing your own skill end-to-end
Here’s a pr-summary skill that drafts a PR description for the current branch.
Step 1 — create the folder. Personal skills live under ~/.claude/skills/ and follow you across projects; project skills go in .claude/skills/ and ship with the repo:
.claude/skills/pr-summary/SKILL.mdStep 2 — write the frontmatter and body:
---
name: pr-summary
description: |
Generate a PR description for the current branch. Pulls commits
since the merge-base with main, summarizes what changed, and
produces Summary / Test plan / Risks sections. Use when the user
asks for a "PR description", "PR body", or is about to open a PR.
---
# Generate a PR description
1. Detect the base branch — try `main`, fall back to `master`.
2. List commits with `git log <base>..HEAD --oneline`.
3. Get the diff stat with `git diff <base>..HEAD --stat`.
4. Output three sections:
- **Summary** — 1-3 bullets of what this PR does.
- **Test plan** — checklist of what was verified.
- **Risks** — known unknowns and what to watch in prod.
5. Do not add co-author trailers or auto-generated notes unless asked.Step 3 — run /pr-summary to verify. Because the description names the scenario, Claude will also pick it up when you say “draft a PR description.”
Step 4 — commit the directory. Everyone who pulls the repo gets the skill.
Inject live data with !command
Skills can run a shell command before the content reaches Claude and splice the output in, so the model reasons over real data instead of guessing. Prefix a line with !`...`:
---
name: summarize-changes
description: Summarize uncommitted changes and flag anything risky.
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above in two or three bullets, then list any
risks: missing error handling, hardcoded values, tests that need
updating. If the diff is empty, say there are no uncommitted changes.This is preprocessing, not something Claude executes — the command runs first, the placeholder is replaced with its output, and Claude only sees the final text. For multi-line commands, use a fenced block opened with ```!. Use $\{CLAUDE_SKILL_DIR\} to point at bundled scripts so paths resolve no matter where the skill is installed.
Run a skill in a subagent
Add context: fork to run a skill in an isolated context that doesn’t see your conversation history. The SKILL.md body becomes the subagent’s prompt, and agent picks the execution profile:
---
name: deep-research
description: Research a topic thoroughly across the codebase.
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly:
1. Find relevant files with Glob and Grep.
2. Read and analyze the code.
3. Summarize findings with specific file references.This only makes sense for skills that contain an actual task. A pure reference skill (“use these API conventions”) forked into a subagent has nothing to do and returns empty.
Make auto-trigger actually work
The description is the entire auto-selection mechanism. Three rules:
- Use trigger words. What do you actually type? “ship”, “cut a release”, “review the diff”, “qa” — put those phrases in.
- Say when NOT to trigger. Add “Skip if the user only wants to discuss release strategy without shipping.”
- Name the artifact. “Produces an updated VERSION file, a CHANGELOG entry, and a pushed PR” beats “handles releases.”
If a skill never fires, paste in real phrases you’ve used. If it fires too often, tighten the scenario or add disable-model-invocation: true so only you can run it. When you have many skills, descriptions get truncated to fit a budget (1% of the context window by default); run /doctor to see whether that budget is overflowing and which skills lost their keywords.
Sharing with a team
- Project skills: commit
.claude/skills/to git. Everyone pulls and uses it — infrastructure as code. Reviewers should glance at anyallowed-toolslines before trusting the repo, since a skill can grant itself broad tool access (it takes effect only after you accept the workspace trust dialog). - Plugins: bundle skills with hooks, agents, and MCP servers, then distribute through a marketplace. Add one with
/plugin marketplace add <owner>/<repo>and install with/plugin install <name>@<marketplace>. Anthropic’sclaude-plugins-officialmarketplace is available the moment you open Claude Code. The plugin system left public beta and stabilized through 2025. - Managed: deploy org-wide through managed settings so every employee gets the same skills.
- User-level: cross-project but personal. Keep them in a private dotfiles repo and symlink into
~/.claude/skills/.
When NOT to use a skill
- One-off question — a direct prompt is faster.
- Reusing a single sentence — a
.claude/commands/<name>.mdfile is enough. - “Run X after every file write” — that’s a hook; it must always fire.
- Parallel investigation across contexts — that’s a subagent (or a skill with
context: fork). - The description is so vague nobody remembers the skill exists — delete it, rewrite it, or merge it.
Common mistakes
- Description like “for code review.” Too vague to match anything. Name the trigger words and the produced artifact.
- Dumping hundreds of lines into
SKILL.md. Keep it under 500 lines; offload detail into referenced files and scripts so they load on demand. - Hardcoding absolute paths. Breaks in another repo. Use relative paths or
${CLAUDE_SKILL_DIR}. - Putting secrets in templates. Skills go to git, so secrets become plaintext commits. Use env vars or a secret manager.
- Confusing skills with hooks. Skills are workflow instructions the model chooses to apply; hooks are shell commands the harness always runs.
- Letting a side-effect skill auto-trigger. Add
disable-model-invocation: trueso Claude never decides to/deployon its own.
FAQ
Q: Are slash commands and skills different things now?
A: No — as of early 2026 custom commands were merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and support the same frontmatter. The skill format adds a directory for supporting files and invocation control, so it’s the recommended choice for anything beyond a single line of text.
Q: How do I stop Claude from triggering a skill automatically?
A: Add disable-model-invocation: true to the frontmatter. Only you can then run it with /name, and its description is dropped from Claude’s context entirely. This is the right setting for skills with side effects like /deploy, /commit, or /send-slack-message.
Q: Why isn’t my skill auto-triggering?
A: Almost always the description is too vague. Add the words you actually type and the artifact it produces. Confirm it’s loaded by asking “What skills are available?” If you have many skills, run /doctor — descriptions get truncated when they exceed the listing budget (1% of the context window), which can strip the keywords Claude needs to match.
Q: Can a skill run scripts, fill templates, or use live data?
A: Yes. Bundle scripts and templates next to SKILL.md and reference them by relative path or ${CLAUDE_SKILL_DIR}. For live data, prefix a line with !`command` and Claude Code runs it first, splicing the output into the prompt before Claude reads it.
Q: Where should a team commit shared skills?
A: In .claude/skills/ at the repo root so they ship with the codebase. Avoid ~/.claude/skills/ for team work — that’s per-user and won’t sync. To share across many repos or bundle hooks and agents, package them as a plugin and distribute through a marketplace.
Related
Tags: #Claude #Claude Code #Tutorial