A Claude Code skill is a folder with a SKILL.md file in it. The file holds instructions, and Claude Code either loads them when your request matches the skill's description or runs them when you type /skill-name. I maintain an open-source skill, explain-to-customer, and use it as the real example here. The post covers how Claude Code skills are found and triggered, which frontmatter fields matter, and when to package one in a plugin.
Everything below is checked against Anthropic's skills documentation and the Agent Skills overview. Claude Code changes quickly, so if your version differs, trust the docs.
What are Claude Code skills?
A skill is a reusable set of instructions, optionally with reference docs, templates or scripts next to it. Claude Code skills follow the Agent Skills open standard, and Claude Code adds its own features on top, such as invocation control and running a skill in a subagent.
The docs suggest making one when you keep pasting the same instructions into chat, or when a section of CLAUDE.md has turned into a procedure rather than a fact. The reason is context. CLAUDE.md is loaded into every session, while a skill loads in stages:
- The name and description sit in Claude's context so it knows the skill exists. Anthropic's overview puts this at about 100 tokens per skill.
- The body of
SKILL.mdenters the conversation only when the skill is invoked. - Supporting files load only when Claude reads them, and scripts run without their source entering the context at all. Only their output does.
So a 300-line release procedure costs almost nothing until the day you release.
Where do Claude Code skills live?
Where you save the folder decides which sessions see it:
| Location | Path | Available in |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | All your projects on this machine |
| Project | .claude/skills/<name>/SKILL.md | This repository. Commit it and your team gets it |
| Nested | <subdir>/.claude/skills/<name>/SKILL.md | Sessions started in that subdirectory, or once Claude works on files there |
| Plugin | <plugin>/skills/<name>/SKILL.md | Wherever the plugin is enabled, as /plugin-name:skill-name |
| Enterprise | .claude/skills/ in the managed settings directory | Everyone on machines where the organization deploys it |
If the same name exists in more than one place, enterprise beats personal and personal beats project. Plugin skills never clash because they are namespaced. A skill folder can also be a symlink.
Claude Code watches these directories, so a new or edited skill takes effect in the running session. If a new one doesn't show up, run /reload-skills. Cloud sessions and Cowork don't read ~/.claude/skills/ on your machine, so for those, commit the skill to the repository or enable it for your claude.ai account.
How are skills triggered?
There are two ways in. You type /skill-name at the start of a message and Claude Code runs it directly, with anything after the name passed in as arguments. Or Claude decides on its own that your request matches the skill's description and loads it.
Two frontmatter fields change who can do what:
| Frontmatter | You can invoke | Claude can invoke | Description in context |
|---|---|---|---|
| (default) | Yes | Yes | Yes |
disable-model-invocation: true | Yes | No | No |
user-invocable: false | No | Yes | Yes |
Use disable-model-invocation: true for anything with side effects, like deploying or committing. You don't want Claude deciding to deploy because the code looks ready. Use user-invocable: false for background knowledge, like how a legacy system works.
Once a skill is invoked, its rendered content stays in the conversation for the rest of the session. Claude Code doesn't re-read the file on later turns. After auto-compaction it re-attaches the first 5,000 tokens of each invoked skill, so put the instructions that matter most at the top.
The SKILL.md format and frontmatter
A SKILL.md has two parts: YAML frontmatter between --- markers, and Markdown instructions after it. The opening --- has to be the first line of the file, or Claude Code treats the whole thing as plain content.
Every field is optional. Only description is recommended, because it is what Claude matches your request against. The common fields:
| Field | What it does |
|---|---|
name | The command name. Defaults to the folder name |
description | What the skill does and when to use it |
when_to_use | Extra trigger phrases, appended to the description |
argument-hint | Shown in autocomplete, for example [issue-number] |
disable-model-invocation | Only you can start it |
user-invocable | Set to false so only Claude can start it |
allowed-tools | Tools Claude can use without asking during the turn that invokes the skill |
model, effort | Override the model or effort level for that turn |
context, agent | context: fork runs the skill in a subagent of the given type |
paths | Globs that limit when the skill activates |
Claude Code silently ignores a field name it doesn't recognize, so a typo like disable-model-invocations does nothing and reports nothing. The combined description and when_to_use text is cut at 1,536 characters in the skill listing, so lead with the main use case.
If you also want the skill to work on claude.ai or through the Skills API, stick to the six fields the open spec allows: name, description, license, compatibility, metadata and allowed-tools. Uploads with any other field fail. The overview also sets stricter rules for name there: at most 64 characters, lowercase letters, numbers and hyphens only, and no anthropic or claude in it.
How to write a Claude Code skill, step by step
This example makes a skill that drafts a pull request description from the current branch.
1. Create the folder
mkdir -p .claude/skills/pr-description
Use ~/.claude/skills/ instead if you want it in every project.
2. Write the description first
The description decides whether Claude ever uses the skill. Say what it does and when to use it, in the third person. Anthropic's authoring guide notes that the description is injected into the system prompt, and a mixed point of view can hurt discovery.
3. Write the body
Save this as .claude/skills/pr-description/SKILL.md:
---
description: Drafts a pull request title and description from the commits on the current branch. Use when the user asks for a PR description, PR body or PR summary.
allowed-tools: Bash(git log *) Bash(git diff *)
---
## Commits on this branch
!`git log --oneline main..HEAD`
## Changed files
!`git diff --stat main...HEAD`
## Instructions
Write a PR title under 70 characters and a description with a short summary,
a list of user-facing changes and a testing section. Do not invent changes
that are not in the commits above.
The !`command` lines are dynamic context injection: Claude Code runs the command before Claude sees the skill and replaces the line with its output, so the instructions arrive with the real commits already inlined. Injected commands never show a permission prompt. Outside auto mode, a command your permission rules don't allow aborts the whole invocation, which is why the example lists both git commands in allowed-tools.
For arguments, put $ARGUMENTS in the body and it is replaced with whatever you type after the command. $0, $1 and so on pick single arguments. This body has no placeholder, so if you type /pr-description mention the migration, Claude Code appends ARGUMENTS: mention the migration to the end of the content instead.
4. Add supporting files when the body grows
The docs suggest keeping SKILL.md under 500 lines and moving long material into separate files that you link from it:
pr-description/
├── SKILL.md
├── reference.md
└── scripts/
└── check-title.sh
To run a bundled script, refer to it through ${CLAUDE_SKILL_DIR}, which expands to the skill's folder wherever it is installed. Use the same variable in allowed-tools, for example Bash(${CLAUDE_SKILL_DIR}/scripts/check-title.sh *), and the script runs without a permission prompt.
5. Test it
Ask something that matches the description ("write a PR description for this branch"), then run /pr-description directly. If it doesn't trigger:
- ask Claude
What skills are available?and check it is listed - make the description use the words people actually type
- run
claude --debugto see YAML parse errors - run
claude plugin validate .claude/skillsto findSKILL.mdfiles whose frontmatter doesn't parse
When the YAML is broken, the skill still loads with no metadata. /pr-description works, but Claude can't match it on its own.
A real example: explain-to-customer
explain-to-customer turns a code change, commit range or pull request into a short MP4, a few PNG slides, Mermaid diagrams and a message you can send to a client. Here is the frontmatter of its SKILL.md:
---
name: explain-to-customer
description: Turns a code change into customer-friendly visuals (short MP4 video, annotated images, Mermaid diagrams) in a chosen visual style and saves them where the user picks. Use when the user runs /explain-to-customer or asks to explain or show a change to a customer or client.
argument-hint: '[commit|range|PR#|"what changed"] [video|image|diagram|all] [style=ID] [out=project|cwd|desktop|videos|PATH] [lang=CODE] [audience=technical] [--yes]'
disable-model-invocation: true
allowed-tools:
- Bash(git status *)
- Bash(git diff *)
- Bash(git log *)
- Bash(git show *)
- Bash(git rev-parse *)
- Bash(gh pr view *)
- Bash(gh pr diff *)
- Bash(node "${CLAUDE_SKILL_DIR}/scripts/*)
- Bash(ffprobe *)
- Read(/${CLAUDE_SKILL_DIR}/**)
---
A run renders video and writes a folder of files, so disable-model-invocation: true makes sure it starts only when you type /explain-to-customer. The argument-hint shows the scope, format and key=value options in autocomplete. allowed-tools holds read-only git and gh commands plus the skill's own Node scripts through ${CLAUDE_SKILL_DIR}. The project is only read, so nothing in that list edits, commits or installs anything in it.
One of the body's ground rules follows from how permission rules match: every bundled script runs as its own bare command, with no &&, pipes or cd around it, because the pre-approval rule only matches the bare command. Long guidance lives in reference/, styles in styles/ and scripts in scripts/, so SKILL.md stays a short entry point.
To install it, use the skills CLI:
npx skills add halitsever/explain-to-customer -g -a claude-code
Or clone it and symlink the skill folder into ~/.claude/skills/, then run /reload-skills if that directory didn't exist before. The project's install guide covers both ways. I use it at the end of the server setup I described in running Claude Code agents in parallel on a server.
When should a skill become a plugin?
A skill on its own is enough for most things. A plugin is for when you want to ship several skills, subagents, hooks or MCP servers as one unit, install it in many projects, or publish versions through a marketplace.
A minimal plugin is a folder with a manifest and a skills/ directory:
my-plugin/
├── .claude-plugin/
│ └── plugin.json
└── skills/
└── review/
└── SKILL.md
{
"name": "my-plugin",
"description": "Team review workflow",
"version": "1.0.0"
}
That skill runs as /my-plugin:review. While developing, load the folder for one session with claude --plugin-dir ./my-plugin and check it with claude plugin validate ./my-plugin. Published plugins install with /plugin install <plugin>@<marketplace>. An enabled plugin's skill descriptions sit in context on every turn, even when nothing from it runs.
Claude Code best practices for skills
These come from Anthropic's Claude Code best practices page and the skills docs.
- Put procedures in skills and facts in
CLAUDE.md. A release checklist belongs in a skill, so it loads only when you release. - Only write down what Claude can't find on its own. Don't explain what the codebase already shows.
- Keep the body short. Once loaded, every line stays in context across turns.
- Use a hook for a rule that must always hold. Claude reads a skill and usually follows it, but Claude Code runs a hook every time its event fires.
- Review
allowed-toolsin skills you didn't write. A project skill's grant applies even in aclaude -prun in a folder you never trusted. - Install skills only from sources you trust. Anthropic's overview warns that a malicious skill can make Claude run code unrelated to its stated purpose.
If you'd like help building skills or Claude Code workflows for your team, my hire page has the details.
FAQ
What is the difference between a skill and a slash command?
Custom commands were merged into skills. A file in .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both give you /deploy. The skill version can also hold supporting files, and it wins if both exist.
Why doesn't Claude use my skill automatically?
Usually the description doesn't match how you ask, the YAML doesn't parse, or disable-model-invocation: true is set. The checks in step 5 find each of these.
Can I use Claude Code skills in scripts?
Yes. In non-interactive mode you put /skill-name in the prompt string and Claude Code expands it before the run. I cover that mode in Claude Code headless mode.
Do Claude Code skills work on claude.ai?
The format is shared, but only with the six spec fields listed above, and Claude Code-only features such as !`command` injection don't run there.