Make a folder .claude/skills/<skill-name>/ in your project (or ~/.claude/skills/<skill-name>/ for every project) and put a SKILL.md file in it. Start the file with YAML frontmatter that has at least a description, then write the instructions in Markdown. At startup Claude only sees the description; the full file loads when you type /skill-name or when Claude decides the skill fits your request. Add disable-model-invocation: true if only you should trigger it, as with a deploy.
What does a minimal skill look like?
.claude/skills/release-notes/SKILL.md
---
name: release-notes
description: Drafts release notes from merged pull requests. Use when asked for release notes or a changelog entry.
disable-model-invocation: true
allowed-tools: Bash(git log *) Read
---
1. Run git log from the last tag to HEAD.
2. Group changes into Added, Changed and Fixed.
3. One line per change, in plain language, no commit hashes.
4. Write the result to CHANGELOG.md under a new heading.
Type /release-notes and Claude follows the steps. The name defaults to the folder name, so you can leave it out.
Where do skills live?
| Scope | Path |
|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md |
| Project (commit to share) | .claude/skills/<name>/SKILL.md |
| Nested in a subfolder | <subdir>/.claude/skills/<name>/SKILL.md, loaded when Claude works in that folder |
| Plugin | <plugin>/skills/<name>/SKILL.md, called as /plugin-name:skill-name |
| Enterprise | The managed settings directory, for everyone your organization deploys to |
Which frontmatter fields should I know?
| Field | What it does |
|---|---|
description | What the skill does and when to use it. Claude decides from this text |
disable-model-invocation | true means only you can run it; the description is not loaded at startup |
user-invocable | false hides it from the / menu so only Claude uses it |
allowed-tools | Tools Claude may use without asking during the turn that runs the skill |
argument-hint, arguments | Autocomplete hint and named arguments |
model, effort | Override the model or effort level for that turn |
context: fork | Run the skill in a forked subagent instead of the main conversation |
paths | Glob patterns; Claude loads the skill on its own only for matching files |
Unknown fields are ignored without an error. One portability note from the skills docs: fields beyond name, description, license, compatibility, metadata and allowed-tools are Claude Code extensions, and skill uploads to claude.ai or the Skills API reject them.
How does a skill load, and what does it cost?
- At startup only the description is in context, so many skills cost little. The description plus
when_to_useis cut at 1,536 characters in the listing. - When used the whole
SKILL.mdbody loads and stays for the rest of the session. - After compaction the latest use of each skill is re-attached, keeping its first 5,000 tokens, within a 25,000-token total.
The docs recommend keeping SKILL.md under 500 lines and putting the important steps first. This is also why moving rarely used instructions out of CLAUDE.md into skills shrinks every request: CLAUDE.md loads every session, a skill body only when needed.
How do I pass arguments?
Text after the command becomes the arguments. Inside SKILL.md:
$ARGUMENTSis everything you typed after the name.$0,$1(or$ARGUMENTS[0]) are positional, counted from 0.$nameworks for arguments you declared inarguments.${CLAUDE_SKILL_DIR}points to the skill's folder, handy for bundled scripts.
If no placeholder takes the input, Claude Code appends it as ARGUMENTS: <value>.
Can a skill include scripts and reference files?
Yes. Anything in the skill folder is available. Mention each file in SKILL.md so Claude knows when to open it:
my-skill/
├── SKILL.md (required)
├── reference.md (read when needed)
├── examples.md (read when needed)
└── scripts/
└── helper.py (run, not loaded)
Scripts are executed rather than read into context, which keeps long logic out of the token count.
What about my old .claude/commands files?
They still work: .claude/commands/deploy.md still gives you /deploy. Commands have been merged into skills, which means Claude may now run a command on its own unless you set disable-model-invocation: true. To add supporting files, move it to .claude/skills/deploy/SKILL.md; you still type /deploy. If both exist with one name, the skill wins.
Does Claude Code ship with skills?
Yes. Bundled skills such as /doctor, /code-review, /batch, /debug and /loop are available in every session. Run /skills to list everything available, filter by name, and press t to sort by token count.
FAQ
Why does Claude not use my skill on its own?
Claude decides from the description. Lead with the words a request would contain, say when to use it, and check that disable-model-invocation is not set.
Do I need to restart after editing a skill?
No. Edits inside existing skill folders apply in the current session. Creating a brand new top-level skills folder needs /reload-skills.
Should a workflow be a skill or a subagent?
Use a skill for instructions you want in the current conversation. Use a subagent, or a skill with context: fork, when the work produces lots of output you do not need to keep.
Can a skill run without permission prompts?
List the tools in allowed-tools. They run without prompting only during the turn that invokes the skill; your deny rules still apply.
Sources
Checked against the official docs on November 17, 2026: Extend Claude with skills, Commands and Manage costs effectively.
See every current command and shortcut in one reference.