Guides ·
How to create Claude Code skills — write down "how to do the job" in one SKILL.md
A Claude Code skill is one folder with one SKILL.md file. Where it goes, what frontmatter fields like name, description and disable-model-invocation control, when Claude loads a skill on its own, how to call one with /name, how skills differ from subagents, and hiio's test-analysis skill as an example.
A Claude Code skill is a file at .claude/skills/<skill-name>/SKILL.md. Personal skills for all your projects go in ~/.claude/skills/, project skills in .claude/skills/, and plugin skills in <plugin>/skills/. Every frontmatter field is optional and only description is recommended. Normally only a skill's description sits in Claude's context, and the full body loads when a request matches. You can call a skill directly with /skill-name, and disable-model-invocation: true stops Claude from calling it on its own. The old .claude/commands/ commands have been merged into skills and still work. A skill runs as instructions inside the main conversation, and context: fork runs it separately in a subagent.
Claude Code: A Hands-On Guide · Part 5 of 10
The short version: a skill is "when this kind of work comes in, do it like this," written down in one file. Make a folder, put a SKILL.md in it, and Claude Code reads it and follows it when a matching request comes in. You can also call it yourself with /skill-name. This post was written by AI (Claude) and checked against the official Claude Code docs — Skills. hiio runs one skill that analyzes website test recordings.
Why skills are useful
You stop explaining the same thing over and over. The official docs suggest writing a skill when you keep pasting the same instructions into chat, or when a section of CLAUDE.md has grown from a "fact" into a "procedure."
The biggest advantage is that a skill is only read when it is needed.
- Normally, only the skill's description sits in context
- When a request matches, the full body loads
- So you can have many skills without weighing down everyday conversations
That is different from CLAUDE.md, which is read in full every time.
Where the files go
One skill is one folder. The folder must contain a SKILL.md.
| Location | Path | Scope |
|---|---|---|
| Enterprise | .claude/skills/<name>/SKILL.md inside the managed settings folder |
Every user the organization deploys to |
| Personal | ~/.claude/skills/<name>/SKILL.md |
All your projects |
| Project | .claude/skills/<name>/SKILL.md |
This repo (commit it to share with the team) |
| Subfolder | <subfolder>/.claude/skills/<name>/SKILL.md |
When working inside that folder |
| Plugin | <plugin>/skills/<name>/SKILL.md |
Where the plugin is enabled. Called as /plugin-name:skill-name |
When names collide, enterprise > personal > project wins. The official docs' example: if deploy exists in both ~/.claude/skills/ and the project's .claude/skills/, /deploy runs the personal one. That is the opposite of subagents (where project beats personal), so don't mix them up. Plugin skills get the plugin name prefixed, so both run even if names overlap.
When you edit or add a skill file, it takes effect in that session without restarting. If you created a top-level skills folder that did not exist when the session started, type /reload-skills.
What the file looks like
This is the first example from the official docs. It lives at ~/.claude/skills/summarize-changes/SKILL.md.
---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above in two or three sentences, then list any risks such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.
The part between the --- lines is the frontmatter, and the body below is the instructions Claude follows. The opening --- must be on the first line of the file.
- There is no
name, so the folder namesummarize-changesbecomes the command name. - The
!`git diff HEAD`line runs the command before Claude reads the skill and is replaced with its output. So Claude gets the actual changes, not the command.
Fields you need to know
From the official docs: every field is optional. Only description is recommended.
| Field | What it controls | If omitted |
|---|---|---|
name |
The name shown in the / menu |
The folder name |
description |
What it does and when to use it. Claude reads this to decide whether to load it | The first line of body text |
when_to_use |
Extra notes on when to use it (appended after description) | — |
disable-model-invocation |
If true, Claude can't call it on its own. Only you call it with /name |
false |
user-invocable |
If false, hidden from the / menu. Only Claude calls it |
true |
allowed-tools |
Tools it can use without asking during the turn the skill was called | — |
argument-hint |
A hint for what to type after /name, e.g. [issue-number] |
— |
context |
fork runs it separately in a subagent |
Inside the main conversation |
agent |
Which subagent type to use with context: fork |
— |
paths |
Turns on automatically only when working with files matching these patterns | — |
There are also arguments, disallowed-tools, model, effort, background, hooks and shell. metadata, license and compatibility are accepted but Claude Code does not use them itself.
Two traps the official docs warn about:
- A misspelled field name is ignored without any error. Skill fields are joined with hyphens, like
disable-model-invocation. That is a different shape from subagents'disallowedTools(camelCase). - If the YAML is broken, the skill loads with no fields at all. It can still be called with
/name, but with no description Claude can't pick it up on its own. Runclaude --debugto see the error.
When Claude uses a skill
From the official docs: Claude picks a skill by matching its description (and when_to_use) against your request. So the docs say to put the words users would actually say into the description.
There is a length limit too. The combined description and when_to_use text is cut off at 1,536 characters in the listing. Put the most important use case first. If you have a great many skills, the whole listing can exceed its budget (1% of the model's context window). When that happens, descriptions are dropped starting with the least-used skills.
Two fields decide who can call a skill:
| Frontmatter | You can call | Claude can call | What is in context |
|---|---|---|---|
| (default) | Yes | Yes | Description always, body when called |
disable-model-invocation: true |
Yes | Not on its own | Description isn't loaded either. Body when called |
user-invocable: false |
No | Yes | Description always, body when called |
The official docs recommend disable-model-invocation: true for work with lasting effects, like /deploy or /commit. You don't want Claude deploying on its own because "the code looks ready."
Calling a skill directly and passing arguments
Type /skill-name at the start of a message. Whatever you type after it fills the placeholders in the body.
---
name: migrate-component
description: Migrate a component from one language to another
---
Migrate the $0 component from $1 to $2. Preserve all existing behavior and tests.
Typing /migrate-component SearchBar JavaScript TypeScript fills $0, $1 and $2 in order. The full input is $ARGUMENTS. If the body has no placeholders and you pass arguments, ARGUMENTS: <your input> is appended to the end of the body. Wrap multi-word values in quotes.
Keeping scripts and reference files alongside
A skill folder can hold other files besides SKILL.md. This is the official docs' example:
my-skill/
├── SKILL.md (required. overview and navigation)
├── reference.md (detailed docs. read when needed)
├── examples.md (examples. read when needed)
└── scripts/
└── helper.py (executed, not loaded)
- Keep SKILL.md under 500 lines. Move detailed material into other files, and link to them from SKILL.md with a note on what each file contains and when to read it.
- Write script paths with
${CLAUDE_SKILL_DIR}. Then the path is right whether the skill is installed as personal, project or plugin.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/render.sh *)
If you use the same path in the body and in allowed-tools, that script runs without a permission prompt.
How skills differ from slash commands and subagents
Slash commands: the official docs say "custom commands have been merged into skills." .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Old commands files keep working. Skills add three things: a folder for reference files, frontmatter that decides who can call it, and Claude loading it on its own. If names collide, the skill wins.
Subagents: the subagents from part 4 work in their own context window and return only a summary. A skill, by default, comes into the main conversation as instructions. Once called, its content stays in the conversation and carries into later turns.
You can also combine them:
- Give a skill
context: forkand it spins up a new subagent with the skill body as its task prompt. That subagent can't see the main conversation history, so the official docs say to use it only for skills with clearly written tasks. - The other way: list skill names in a subagent's
skillsfrontmatter, and the full skill bodies are preloaded when that subagent starts.
Our file: test-analysis
hiio records testers' screens and voices with a website test recorder. Turning those ZIPs into a "things to fix" document is a personal skill, at ~/.claude/skills/test-analysis/SKILL.md. Here is the frontmatter, with the description translated from Korean:
---
name: test-analysis
description: Takes a ZIP made by the website test recorder (website-test-*.zip, formerly moneysofa-test-*.zip), analyzes it and produces a "things to fix" document. Use when the user hands over a test recording ZIP and says "analyze this", "sort out the test results", or "pull out what to fix", or gives a folder containing summary.md, hesitations.json and memos.json. When given several ZIPs at once, merge the same problems.
---
The body is laid out in this order:
# Test recording analysis
## 0. Principles (recordings never leave the machine, masked values are not restored)
## 1. Unpack (a new empty folder per ZIP, never run scripts inside)
## 2. Transcribe the voice
## 3. Group by time
## 4. Build the "things to fix" document (item template and priority P0–P3)
## 5. Merge multiple ZIPs
## 6. Report
Three things we settled on after using it:
- The description includes the user's actual phrases and file names. Phrases like "analyze this" and "pull out what to fix," and file names like
summary.mdandhesitations.json. The official docs also say that if a skill isn't triggering, first check "whether the description includes words people actually use." - The must-follow rules sit at the top, in "0. Principles." Per the official docs, when a conversation is compacted, only the beginning of an invoked skill is reattached. So important instructions belong at the top.
namematches the folder name. Leaving it out would use the folder name anyway, but writing it means anyone opening the file sees right away that it is called as/test-analysis.
This skill is still a single SKILL.md.
Common mistakes
- Leaving the description empty or too broad. Too narrow and it never triggers; too broad and it triggers all the time. If it triggers too often, narrow the description or add
disable-model-invocation: true. - Typos in field names. They are ignored without an error.
disable_model_invocation(underscores) does nothing. - "It followed the rule once, then stopped." A skill enters the conversation once, when it is called, and the file isn't re-read on later turns. If a rule must be enforced every single time, the official docs' answer is to move it to hooks. After a conversation is compacted, call the skill again.
- Trying to block tools with
allowed-tools. This field lets tools run "without asking." It does not block other tools. To block them, usedisallowed-toolsor permission settings. - Editing synced skills. Skills synced down from claude.ai (the
syncedfolder) can be overwritten at the next sync. Keep skills you want to edit in a folder you created yourself.
FAQ
What is the difference between skills and .claude/commands/ commands?
Both create /name and work the same way. The official docs say commands have been merged into skills. Skills additionally get a folder for reference files, frontmatter that decides who can call them, and Claude loading them on its own. You can leave old commands files as they are.
How do I stop Claude from calling a skill on its own?
Add disable-model-invocation: true to the frontmatter. Then the description isn't loaded into context either, and the skill only runs when you call it with /name. It suits work with lasting effects, like deploying, committing or sending messages.
My skill isn't being triggered. Where do I start?
The official docs give this order: (1) check whether the description has words people actually use, (2) ask "What skills are available?" to see if it is listed, (3) rephrase your request closer to the description, (4) call it directly with /name. Check for broken YAML with claude --debug.
Will making lots of skills slow things down?
Normally only names and descriptions are loaded, and bodies are read only when called. But if the whole listing exceeds its budget, descriptions are dropped starting with the least-used skills. /doctor shows how much the listing takes up, and /skill-doctor finds skills you don't use.
Can I use skills in other AI tools?
Claude Code skills follow the open Agent Skills standard. But the only frontmatter fields that work outside Claude Code (such as uploading to claude.ai) are name, description, license, compatibility, metadata and allowed-tools. Fields like context: fork are Claude Code only.
Sources
- Claude Code docs — Skills
- Claude Code docs — Subagents (preloading skills)
- Agent Skills open standard
- How to create Claude Code subagents (part 4)
- 4 Claude Code hooks examples (part 3)
Written with AI (Claude) and checked against the linked sources.