Slash commands give you reusable prompts. Skills give you reusable workflows: a set of instructions, plus optional supporting files, that Claude loads when a task calls for it or when you type /skill-name. A /commit prompt writes a commit message. A review-pr skill can describe the whole review: read the diff, check CI, look at related issues, and summarize findings in a fixed format.
This lesson was checked against Anthropic's Claude Code skills documentation on 2026-10-09. The examples below are templates I did not run in a live session. Claude Code changes often, so if a field behaves differently on your version, the docs win.
What a skill actually is
A skill is a folder containing a file named SKILL.md. The file has two parts: YAML frontmatter between --- lines, then Markdown instructions. Claude keeps each skill's name and description in context so it can decide when to use one. The full instructions load only when the skill is invoked.
Where the folder lives decides who gets the skill:
~/.claude/skills/<skill-name>/SKILL.mdfor every project you open.claude/skills/<skill-name>/SKILL.mdinside a repository, for that project (commit it and your team gets it)
The older format, a single Markdown file in .claude/commands/, still works and creates the same slash command. Per the docs, a skill is preferred for new work because it can also carry supporting files.
Anatomy of a SKILL.md
Every frontmatter field is optional, but description is recommended because Claude uses it to decide when to apply the skill. The fields you will use first:
| Field | What it does |
|---|---|
name | The slash command name. Defaults to the folder name. |
description | What the skill does and when to use it. Put the key use case first; the combined description and when_to_use text is truncated at 1,536 characters in the skill listing. |
when_to_use | Extra trigger phrases or example requests, appended to the description. |
argument-hint | Autocomplete hint, such as [pr-number]. |
disable-model-invocation | true means only you can run it, by typing /name. |
allowed-tools | Tools Claude may use without asking during the turn that invokes the skill. |
context | Set to fork to run the skill in a separate subagent context. |
The docs list more fields (model, effort, paths, hooks, user-invocable and others). Start with the table above and add the rest only when you need them.
The body can use $ARGUMENTS, which is replaced with whatever you type after the skill name. If you pass arguments and the body has no placeholder, Claude Code appends ARGUMENTS: <your input> to the end so Claude still sees them.
A first skill: review a pull request
Save this as .claude/skills/review-pr/SKILL.md. Note the folder name matches the skill name and the file is always called SKILL.md.
---
name: review-pr
description: Reviews a GitHub pull request by reading the diff, checking CI status and summarizing risks. Use when the user asks to review a PR or gives a PR number.
argument-hint: "[pr-number]"
disable-model-invocation: true
---
Review pull request $ARGUMENTS.
1. Fetch the PR title, description, linked issues and full diff. Use the GitHub CLI or a GitHub MCP server if one is configured.
2. For each changed file, read the current version in the codebase so you understand the context around the change.
3. Look for bugs, security problems, missing error handling and missing tests.
4. Check the CI results. If any check failed, read the failure output and say whether the PR caused it.
5. Report in this format:
- Verdict: approve, request changes, or comment
- Critical issues (file and line)
- Suggestions
- Anything you could not check
Do not post comments to GitHub. Only report to me.
Run it with /review-pr 142. Because disable-model-invocation is true, Claude will not start a review on its own; you decide when. Drop that line if you want Claude to pick the skill up from a plain request like "review PR 142".
Add supporting files
Keep SKILL.md focused and move detail into files next to it. The docs recommend keeping SKILL.md under 500 lines.
review-pr/
├── SKILL.md # overview and navigation
├── checklist.md # detailed review criteria, loaded when needed
└── scripts/
└── ci-summary.sh # a helper script, run rather than read
Reference each file from SKILL.md and say when Claude should open it, for example: "For the full security checklist, see checklist.md." Files Claude never needs on a given run cost no context.
Skills vs slash commands: the practical distinction
A short, single-purpose prompt can stay a command file or a very small skill. Reach for the fuller skill structure when:
- The workflow has several distinct phases and the order matters
- It needs reference files or scripts alongside the instructions
- You want to control whether you, Claude or both can start it
- Several people on the team should run the same process the same way
If you are doing something once, or it has two steps, a regular prompt is enough. The overhead of writing and maintaining a skill is not worth it for simple tasks.
More skill patterns
Three skeletons to adapt. Each is a template, not tested output.
Implement a feature from a spec (add-feature). Steps: read the spec in $ARGUMENTS, read CLAUDE.md and the closest existing implementation, list the files to change, implement one file at a time with type-checking after each, write and run tests, then show the diff before committing. Make it manual-only (disable-model-invocation: true) because it edits many files.
Debug an error (debug-error). Steps: parse the error in $ARGUMENTS, read the failing code, trace callers backwards, check recent history with git log on the files involved, state the root cause, then propose the fix and wait for your confirmation before changing anything. The "wait for confirmation" step is the value here, so write it in plainly.
Research in isolation (context: fork). Adding context: fork runs the skill in its own subagent with its own context. The subagent does not see your conversation, so the skill's instructions must stand on their own, and the skill needs an explicit task rather than only guidelines. The agent field picks the subagent type.
Invoking skills
Two ways, both documented:
/review-pr 142
Review PR 142 with the review-pr skill
The first bypasses matching entirely, which also makes it the quickest way to tell whether a problem is in the instructions or in the description. If a skill is not triggering on plain requests, the fix is nearly always a more specific description that uses the words you would actually type. For a full walkthrough of writing, testing and debugging a skill, see How to write your first Claude skill (SKILL.md).
Skills across a team
Skills in .claude/skills/ are committed to the repository, so everyone using Claude Code in it gets the same review-pr and debug-error workflows. You are encoding your team's practice into something Claude follows, instead of retelling it each time. New developers get the standard process applied from their first session.
One caution from the docs: when a skill is invoked, its text enters the conversation once and stays there; Claude Code does not re-read the file on later turns. Write instructions that apply to the whole task, put the most important rules first, and move anything that must hold every single time into a hook.
When skills are overkill
Not every workflow needs one. If it is a one-off, use a prompt. If it has two steps, a command with a good prompt is enough. Save skills for workflows that are genuinely complex and genuinely repeated.
The next lesson covers hooks, the mechanism for automatically running scripts before or after Claude uses a tool. Hooks work at a different layer: they are reactions to Claude's actions, not instructions Claude chooses to follow. For when to use which, see skills, hooks and subagents explained.