Claude Code skills
By Mari Luukkainen · 6 min read · Last updated
On this page
A Claude Code skill is a folder with a SKILL.md file of instructions that Claude loads when a task matches its description, or when you type /skill-name. Only the short description sits in context until then, so a long checklist costs almost nothing until it is used. Facts on this page come from Anthropic's skills docs, checked 11 November 2026.
Skills are one of the add-ons covered in what Claude Code is. This page covers when a skill is the right tool, the file format, where skills live, how they load and a first skill you can copy. Skill content counts toward your usage like any other context, and the plans are compared on Claude Code pricing.
Ask AI about this pageChatGPTClaudePerplexityGoogle AI ModeGrok
When should you write a skill?
Anthropic's rule of thumb: write a skill when you keep pasting the same instructions, checklist or procedure into the chat, or when a section of CLAUDE.md has turned into a procedure rather than a fact (skills docs). CLAUDE.md loads into every session. A skill's body loads only when it is used.
| You want | Use |
|---|---|
| Facts Claude needs in every session, such as the build command or the folder layout | CLAUDE.md |
| A procedure you run now and then, such as a release checklist | A skill |
| Something that must happen every time, such as a format step after each edit | A hook |
| A separate worker with its own context and tools | A subagent |
Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Old command files keep working, and if both exist with the same name, the skill wins.
What does a skill file look like?
A skill is a folder. The only required file is SKILL.md, which has YAML frontmatter between --- markers at the very top, then Markdown instructions. The frontmatter must start on the first line of the file.
---
name: release-notes
description: Writes release notes from the commits since the last tag. Use when the user asks for release notes or a changelog entry.
disable-model-invocation: true
allowed-tools: Bash(git log *) Bash(git describe *)
---
1. Find the last tag with git describe --tags --abbrev=0.
2. List the commits since that tag with git log.
3. Group them under Added, Changed and Fixed.
4. Write one plain sentence per change. Leave out merge commits.
5. Show the notes. Do not commit or push anything.Anthropic suggests keeping SKILL.md under 500 lines. Longer reference material goes in separate files in the same folder, such as reference.md or examples.md, linked from SKILL.md so Claude knows when to open them. Scripts in a scripts/ folder are run, and their text is not loaded into context.
Where do skills live?
| Location | Path | Applies to |
|---|---|---|
| Personal | ~/.claude/skills/<skill-name>/SKILL.md | All your projects on this machine |
| Project | .claude/skills/<skill-name>/SKILL.md | This repository. Commit it to share with the team |
| Nested | <subdir>/.claude/skills/<skill-name>/SKILL.md | Sessions started in or below that folder |
| Plugin | <plugin>/skills/<skill-name>/SKILL.md | Wherever the plugin is enabled, called as /plugin-name:skill-name |
| Enterprise | The managed settings directory | Everyone on machines where the organization deploys it |
When two skills share a name, enterprise beats personal and personal beats project. Plugin skills carry the plugin name, so they do not collide. Skills enabled on your claude.ai account are also synced to ~/.claude/skills/synced/ (skills docs).
How does Claude decide to use a skill?
In a normal session Claude sees each skill's description, and it loads the full skill when your request matches. You can also call it yourself: type /release-notes at the start of a message to run it directly. Two frontmatter fields change who may start it:
| Frontmatter | You can run it | Claude can run it | Description in context |
|---|---|---|---|
| Default | Yes | Yes | Always |
| disable-model-invocation: true | Yes | No | No |
| user-invocable: false | No | Yes | Always, hidden from the / menu |
Use disable-model-invocation for anything with side effects, such as a deploy, so it runs only when you ask. Use user-invocable: false for background knowledge you never call by hand.
The description and the optional when_to_use text are cut at 1,536 characters in the skill listing, so put the main use case first. Once loaded, a skill stays in the conversation. When the context is compacted, Claude Code re-attaches the latest use of each skill, keeping the first 5,000 tokens per skill within a shared budget of 25,000 tokens (skills docs).
Which frontmatter fields matter most?
All fields are optional, and description is the one Anthropic recommends. Field names must match exactly: an unknown field is ignored without an error.
- name. The command name in the / menu. Defaults to the folder name.
- description. What the skill does and when to use it. Claude matches requests against this.
- allowed-tools. Tools Claude may use without asking during the turn that runs the skill, such as Bash(git add *). It does not block other tools, and it clears with your next message.
- disallowed-tools. Tools removed while the skill is active.
- argument-hint and arguments. An autocomplete hint and named arguments. In the body, $ARGUMENTS expands to everything you typed after the command, and $0, $1 to single arguments.
- model and effort. The model and effort level for that turn.
- context: fork. Runs the skill in a forked subagent, with agent naming the type, such as Explore or Plan. The subagent does not see your conversation, so the instructions must stand alone.
- paths. Glob patterns that limit when Claude loads the skill on its own.
- hooks. Hooks that register when the skill runs.
A skill can also pull live data in before Claude reads it. A line with an exclamation mark and a command in backticks, such as git diff HEAD, is run first and replaced with its output (skills docs).
How do you build your first skill?
- Pick a procedure you have typed into Claude Code at least three times. A release checklist or a pre-deploy check is a good first one.
- Create .claude/skills/<name>/SKILL.md in the project, or under ~/.claude/skills/ if you want it everywhere.
- Write a description that starts with what the skill does and names the requests that should trigger it.
- Add disable-model-invocation: true if the skill changes anything outside the repo.
- Write the steps as a numbered list, with the exact commands, and say what Claude must not do.
- Run it with /<name> and read what it did. Tighten the steps where it guessed.
For the habits around skills, such as keeping CLAUDE.md short and moving procedures out of it, see Claude Code best practices.
Do Claude Code skills work elsewhere?
Partly. Outside Claude Code, in claude.ai uploads and the Skills API, only name, description, license, compatibility, metadata and allowed-tools are accepted, and other keys cause an error on upload (skills docs). A skill that uses context: fork, hooks or paths is Claude Code only.
Frequently asked questions
What is a skill in Claude Code?
A folder with a SKILL.md file of instructions. Claude loads it when a request matches its description, or you run it with /skill-name.
Where do I put Claude Code skills?
In .claude/skills/<skill-name>/SKILL.md for one project, or ~/.claude/skills/<skill-name>/SKILL.md for all your projects.
What is the difference between a skill and a slash command?
Custom commands are now part of skills. Both .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md create /deploy. A skill adds a folder for extra files, frontmatter that controls who can run it, and loading on its own when relevant.
Do skills use up context?
Only a little until they run. The description is in context, and the full skill loads when it is used. A skill with disable-model-invocation: true keeps even its description out of context.
How do I stop Claude from running a skill by itself?
Add disable-model-invocation: true to the frontmatter. Then only you can start it, with /skill-name.
Next guideClaude Code hooks →