Skills in Claude Code
A skill is a saved instruction file that teaches Claude how to do a specific job. Write it once, store it in your project, and call it any time with a simple slash command — no re-typing needed.
The problem skills solve
Imagine you write tests the same way on every project — same structure, same naming conventions, same coverage rules. Without skills, you either paste those instructions into every chat, or dump them all into CLAUDE.md where they sit in context even when you are not writing tests. Skills give you a third option: store the instructions in a dedicated file and load them only when you actually need them.
| Approach | Drawback |
|---|---|
| Paste into every chat | Same multi-step instructions repeated each session |
| Put everything in CLAUDE.md | Loads on every session — spends context budget even when unused |
| Store as a skill | Instructions stay on disk; loaded only when you type /skill-name |
How a skill is structured
A skill is a folder inside .claude/skills/. The folder name becomes the slash command. Inside the folder, SKILL.md is the only required file. You can add extra files alongside it for templates, examples, or scripts that the skill references.
SKILL.md focused on the essentials. Put detailed reference material in separate files and link to them from the main file. Claude only loads those extra files when it actually needs them.Worked example: /write-tests
This skill tells Claude exactly how to write unit tests for any file you point it at — consistent structure, consistent naming, no repeated instructions. After building it you can run /write-tests src/utils/date.ts and Claude will follow the same approach every time.
Step 1 — create the skill folder
Project skills go in .claude/skills/ — available only in this project. Personal skills go in ~/.claude/skills/ and work across every project you open.
Step 2 — write SKILL.md
The file has two parts. The YAML block at the top (between ---) sets metadata and controls how Claude invokes the skill. The Markdown below it is the actual instruction Claude follows.
| Field | What it does |
|---|---|
| description | Claude uses this to decide when to auto-load the skill |
| disable-model-invocation: true | You trigger it manually — Claude won't run it on its own |
| allowed-tools | Claude can Read files and run jest without asking each time |
| $ARGUMENTS | Replaced with whatever you type after /write-tests |
Step 3 — use the skill
Type the skill name followed by the file path. Claude reads SKILL.md, substitutes $ARGUMENTS with your path, and works through the steps.
Where skills live
You can store skills at three levels depending on how widely you want to share them. When two skills share the same name, the broader scope wins.
| Scope | Path | Available to |
|---|---|---|
| Personal | ~/.claude/skills/skill-name/ | Every project you open |
| Project | .claude/skills/skill-name/ | Only this project — commit to Git for the team |
| Enterprise | Managed settings (admin) | All users in your organisation |
Key frontmatter fields
The YAML block at the top of SKILL.md controls how and when the skill is used. Every field is optional — start with just description and add others as you need them.
| Field | What it does | When to use it |
|---|---|---|
| description | Tells Claude what this skill is for and when it applies | Always — helps Claude decide whether to suggest the skill |
| name | Overrides the display name (defaults to the folder name) | When your folder name is not human-friendly |
| disable-model-invocation | Prevents Claude from calling the skill on its own | For actions with side effects you want to trigger yourself |
| user-invocable | Set false to hide the skill from the / menu | For background reference material, not user-facing commands |
| allowed-tools | Tools Claude can use without a per-use approval prompt | When the skill needs to run scripts or read files automatically |
| arguments | Named placeholders for positional arguments ($name, $0, $1) | When your skill accepts more than one input value |
| context: fork | Runs the skill in an isolated sub-agent | For heavy tasks that should not pollute the main conversation |
Who can invoke a skill
By default any skill can be triggered by you or by Claude. Two flags let you lock down that behaviour when you need more control.
| Mode | Setting | You | Claude | Good for |
|---|---|---|---|---|
| Both (default) | No extra field needed | Yes | Yes | Code review helpers, formatting standards, style guides |
| You only | disable-model-invocation: true | Yes | No | /deploy, /release — anything with real-world effects |
| Claude only | user-invocable: false | No | Yes | Background knowledge, coding conventions, domain glossaries |
Passing arguments
Anything you type after the skill name is available inside the skill as $ARGUMENTS. If you need to access individual words separately, use $0 for the first, $1 for the second, and so on.
One argument — $ARGUMENTS
Multiple arguments — $0, $1
Built-in skills
Claude Code includes a handful of ready-made skills. You do not need to create any files for these — they are available in every session. Call them the same way as your own skills.
| Command | What it does |
|---|---|
| /simplify | Makes code shorter and clearer without changing its behaviour |
| /debug | Walks through a bug methodically — hypothesis, investigation, fix |
| /batch | Applies the same operation to a list of files at once |
| /loop | Repeats a task in a cycle until you tell it to stop |
| /claude-api | Lets Claude call the Anthropic API directly from within a session |
SKILL.md files internally — they work exactly the same way as skills you write yourself.Before you continue
- Skills are folders in
.claude/skills/with a requiredSKILL.mdfile. - Invoke with
/skill-name; pass arguments after the command. - Use
disable-model-invocation: truefor skills you want to trigger yourself. - Project skills can be committed to Git so the whole team shares them.
- Next lesson: Debugging & Troubleshooting.
What's Next
Skills are powering your Claude Code workflow. Next: debugging — how to diagnose, fix, and iterate when things go wrong.