Claude Code skills: what they are and how to write one
A Claude Code skill is a folder with a SKILL.md that Claude loads when relevant or you call with a slash. See the format, frontmatter fields and an example.
A Claude Code skill is a folder containing a SKILL.md file: Markdown instructions with a short YAML header. Claude loads it when your request matches its description, or you run it yourself with /skill-name. Skills are where procedures live (how to cut a release, how to add a migration), so they do not take up room in your CLAUDE.md on every session.
#What is a skill, and why not just use CLAUDE.md?
Both give Claude instructions, but they load differently. CLAUDE.md is read at the start of every session, so it should hold short facts that are always true: commands, layout, conventions. A skill's description is always visible to Claude, but its full content only loads when it is invoked. That makes skills the right home for long, task-specific procedures.
A good test: if you would write "when I ask to X, do steps 1 to 6", it is a skill. If it is "we use pnpm", it is CLAUDE.md.
Skills live in these places:
| Scope | Path |
|---|---|
| Personal, all your projects | ~/.claude/skills/<name>/SKILL.md |
| Project, shared via git | .claude/skills/<name>/SKILL.md |
| A subdirectory | <subdir>/.claude/skills/<name>/SKILL.md |
| Plugin | <plugin>/skills/<name>/SKILL.md, used as /plugin-name:skill-name |
| Organization | in the managed settings directory |
If a name exists in several scopes, enterprise beats personal, and personal beats project. Claude Code picks up added, edited or removed skills within the current session, with one exception: if you create a top-level skills directory that did not exist when the session started, run /reload-skills.
#How do you write a SKILL.md?
A minimal skill is a directory with one file. This one summarizes your uncommitted work:
---
name: summarize-changes
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`
Summarize the changes in two or three bullets, then list any risks:
missing tests, changed public APIs, leftover debug code.
The line starting with !` runs the shell command before Claude sees the skill and substitutes its output, so the diff is already in the prompt. A failed command aborts the invocation. For multi-line commands, use a fenced block opened with ```!. If you would rather block this feature, set "disableSkillShellExecution": true in settings.
#What frontmatter fields matter?
The frontmatter must start on the file's first line. Field names must match exactly; unknown fields are ignored without an error. The ones you will actually use:
| Field | What it does |
|---|---|
name | The name in the / menu. Defaults to the directory name. |
description | What the skill does and when to use it. Claude uses it to decide when to load the skill. |
when_to_use | Extra trigger phrases or example requests, appended to the description. |
argument-hint | Autocomplete hint such as [issue-number]. |
arguments | Named positional arguments for $name substitution. |
disable-model-invocation | true stops Claude from loading it automatically; manual only. |
user-invocable | false hides it from the / menu so only Claude uses it. |
allowed-tools | Tools pre-approved while the skill runs. It does not restrict other tools. |
model, effort | Override the model or effort for the turn. |
context: fork | Run the skill in a subagent (with agent to pick which). |
paths | Globs limiting automatic activation to matching files. |
#How does Claude decide to use a skill?
By the description. Claude sees the name and description of every available skill and loads one when your request fits. That makes the description the most important line you write:
- Lead with the use case. The combined
descriptionandwhen_to_usetext is truncated at 1,536 characters in the skill listing, so put the key trigger first. - Say what it does and when to use it, in the words you would actually type: "Use when the user asks to cut a release or bump the version".
- Test it with realistic prompts in a fresh session, with and without the skill. Context left over from writing the skill can hide gaps in the instructions.
If a skill has side effects (deploy, publish, send), set disable-model-invocation: true so it only ever runs when you type /deploy. If it is background knowledge you never call by name, use user-invocable: false.
#How do arguments and scripts work?
$ARGUMENTS is everything typed after the name. $0, $1 and so on pick one by position, and arguments: [component, from, to] lets you write $component, $from, $to. Quote values with spaces. If you use no placeholder, the arguments are appended as ARGUMENTS: <value>. Escape a literal dollar sign with a backslash.
A skill can carry more than one file:
release/
├── SKILL.md # overview and navigation, keep under 500 lines
├── reference.md # read only when needed
└── scripts/
└── bump.sh # executed, not loaded into context
Mention the supporting files from SKILL.md so Claude knows when to read them. ${CLAUDE_SKILL_DIR} resolves to the skill's folder, which lets you pre-approve a bundled script:
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/bump.sh *)
Scripts are the efficient part: a script that Claude runs costs its output, not its source.
#What are good first skills, and how do they relate to commands?
Pick a procedure you have explained twice:
- Release: bump the version, update the changelog, tag, build.
- New migration or new endpoint, following your conventions.
- Pull request description from the branch diff.
- A review checklist for your stack, run with
context: forkso the reading stays out of your main context. - Triage: reproduce a bug from an issue number, in a fixed order of steps.
Keep each skill to one job, under 500 lines, and write the steps in the order you would do them. Claude Code also ships bundled skills such as /simplify, /loop and /debug; list what you have with /skills.
#Skills and commands
Custom slash commands have been merged into skills: a .claude/commands/deploy.md file and a .claude/skills/deploy/SKILL.md both give you /deploy, and a skill wins on a name clash. See Claude Code slash commands for the command side. For deterministic behavior, such as always running a formatter after an edit, a hook is the better tool than a skill, since a skill is guidance Claude chooses to follow.
#In Relais
Relais sessions are real Claude Code sessions, and the composer offers / for commands and skills. A Relais session template can name skills to use alongside standing rules for a session. See features.