skip to content

Skills & Custom Commands

Skills package reusable instructions as SKILL.md folders that Claude loads on demand or you run as /name; custom commands now merge into them. Asked because skills differ from CLAUDE.md and hooks.

part ofClaude Coderead it →
on this pageshow

explore

questions

17

In Claude Code, how do you turn your team's database-migration wiki page into a skill, and what goes in SKILL.md?

level: juniorimportance: must knowfreq 28%

answer

  1. a folder, not a loose file
  2. the file name is fixed
  3. YAML between dashes on line one
  4. the one recommended field
  5. folder name becomes the command

basics

~10 s

Create a folder such as .claude/skills/db-migrations/ holding a SKILL.md: YAML frontmatter between --- markers starting on line one, with a description of when to use it, then the migration rules as concise Markdown.

solid answer

~40 s

A skill is a directory whose required file is `SKILL.md`. To share it with the team, commit `.claude/skills/db-migrations/SKILL.md`; for yourself only, use `~/.claude/skills/db-migrations/SKILL.md`. The file opens with YAML frontmatter between `---` markers, and the opening `---` must be the very first line. Every field is optional, but `description` is the one the docs recommend, because Claude matches requests against it to decide when to load the skill on its own. The folder name, or a `name` field, becomes the command: `/db-migrations`. Below the frontmatter, the wiki page becomes short, imperative Markdown instructions, with long reference material moved into supporting files beside it. By default only the name and description sit in context up front; the body loads when the skill is invoked.

code

markdown · 13 lines
markdown
---
name: db-migrations
description: Write and review database migrations for this repo. Use when adding a table or column, changing a schema, or creating a migration file.
---

# Database migrations

1. Never edit a migration that has already run; add a new one.
2. Give every migration a rollback.
3. Split a column rename into add, backfill and drop across releases.
4. Prefix migration file names with a UTC timestamp.

For backfill patterns, see [backfills.md](backfills.md).

go deeper

for a junior

Recall the path .claude/skills/<name>/SKILL.md, that frontmatter sits between --- markers on line one, and that description is the field Claude matches requests against.

for a middle

Explain how the command name is derived, what happens when description is missing, and why the older .claude/commands file format still works but lacks supporting files.

for a senior

Show you can debug a skill that silently misbehaves: unparsed YAML loading with empty metadata, frontmatter not on line one, misspelled fields ignored, and the tools that surface each.

for a principal

Weigh how a team keeps converted wiki procedures short and current as skills, and who reviews committed skills, since every repository skill ships to everyone who clones it.

## What a skill is A **skill** in Claude Code is a packet of instructions that loads **on demand**. Unlike `CLAUDE.md`, which is read into every session, a skill's body enters the conversation only when the skill is used, either because you type `/skill-name` or because Claude decides the request matches the skill's description. That makes it the right home for a procedure such as "how we write database migrations": long, specific, and only relevant some of the time. ## The folder and the file A skill is a **directory**, and its one required file is named exactly `SKILL.md`: - `.claude/skills/db-migrations/SKILL.md` is a **project** skill. Commit it, and everyone who clones the repository gets it. - `~/.claude/skills/db-migrations/SKILL.md` is a **personal** skill, available in all your projects on this machine. - Other files in the same folder (reference documents, examples, scripts) are **supporting files** that load only when Claude needs them. The command you type comes from the directory name, so this folder creates `/db-migrations`. A `name` field in the frontmatter can set a different command name, and the directory name still invokes the skill too. An older format still works: a single Markdown file in `.claude/commands/`, such as `.claude/commands/db-migrations.md`, also creates `/db-migrations`. Custom commands were merged into skills, so both behave the same way, but a command file cannot carry supporting files and does not accept the `name` or `paths` fields. Prefer the skill folder for new work. ## The frontmatter block The file starts with YAML between two `---` lines, then Markdown. The fields that matter first: | Field | Required | What it does | | :- | :- | :- | | `description` | Recommended | What the skill does and when to use it; Claude matches requests against it | | `name` | No | The command name; defaults to the directory name | | `when_to_use` | No | Extra trigger phrases, appended to `description` in the skill listing | Other fields, such as `paths`, `context`, `model`, `effort` and `hooks`, change how and where the skill runs, and none of them is needed for a first working skill. If you leave `description` out, Claude Code uses the first non-empty line of the body instead, which is usually a heading that says nothing about when to use the skill. ## Writing the body Turn the wiki page into instructions, not narrative: 1. State the rules as commands ("Add a new migration; never edit one that has run"). 2. Keep the body short, because once invoked it stays in context across turns and every line is a recurring cost. The docs suggest keeping `SKILL.md` under 500 lines. 3. Move long material, such as backfill patterns or a catalogue of past incidents, into supporting files and link to them from `SKILL.md`. ## When the file does not behave Claude Code is forgiving in ways that hide mistakes: - **Frontmatter not on line one.** If anything, even a heading, comes before the opening `---`, the whole file, markers included, is treated as skill content with no fields set. - **YAML that does not parse.** The skill still loads with empty metadata: `/db-migrations` works, but there is no description for Claude to match. Run `claude --debug` to see the parse error, or `claude plugin validate .claude/skills` to list `SKILL.md` files whose frontmatter fails to parse. - **A misspelled field.** Field names must match the reference exactly, hyphens included (and `when_to_use` uses underscores). An unrecognised field is ignored without an error. ## Testing the result Check both ways a skill can start: 1. Type `/db-migrations` at the start of a message. If the skill runs, the file is in the right place and its name resolved. 2. In a fresh session, ask something the description covers, such as "add a nullable column to the orders table". If Claude loads the skill on its own, the description is doing its job; if not, the frontmatter or the wording needs attention. 3. Ask Claude "What skills are available?" to confirm the skill is listed at all. Claude Code watches the skill directories (except in bare mode), so editing `SKILL.md` in a running session takes effect without a restart. A brand-new top-level skills directory that did not exist at startup needs `/reload-skills` before its skills appear.

  • The skill runs when you type /db-migrations, but Claude never loads it on its own. What in the file could cause that?
    Check the frontmatter. If the YAML between the markers does not parse, Claude Code still loads the skill with no fields set, so `/db-migrations` works while there is no `description` to match against; `claude --debug` shows the parse error. If the opening `---` is not on line one, the whole file is treated as body. A misspelled field name is silently ignored, so the value you meant to set never applies.
  • What happens if SKILL.md has no description field at all?
    The skill still loads. Claude Code uses the first non-empty line of the Markdown body as the description. That line is often a heading such as `# Database migrations`, which rarely says when the skill applies, so write an explicit `description` that names the task and the situations it covers.

  • Any Markdown file anywhere in the repository is picked up as a skill.
  • The name field is mandatory, or the skill will not load.
  • A title line above the frontmatter block is fine; the parser skips it.
  • A misspelled frontmatter field makes Claude Code refuse to load the skill.
  • The whole SKILL.md body is read into context at the start of every session.
open as a page

In Claude Code, what happens to existing .claude/commands/*.md files now that custom commands are merged into skills?

level: juniorimportance: must knowfreq 24%

basics

~10 s

They keep working. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and behave the same way; the skill wins a name clash, and new work should use the skill folder.

open as a page

In Claude Code, when should an instruction live in a skill rather than in CLAUDE.md?

level: juniorimportance: must knowfreq 30%

basics

~20 s

CLAUDE.md loads into every session, so it suits short always-true facts and rules; a skill loads its body only when invoked by /name or matched by its description, so it suits procedures and long reference material needed sometimes.

open as a page

How do a Claude Code skill's description, SKILL.md body and supporting files each reach Claude's context, and when?

level: middleimportance: must knowfreq 20%

basics

~20 s

By default the description sits in the skill listing on every turn; the SKILL.md body enters context only when the skill is invoked, then stays; supporting files load only when Claude follows a pointer to them, and bundled scripts run without being read.

open as a page

In a Claude Code SKILL.md, how do disable-model-invocation: true and user-invocable: false differ, and which keeps a /deploy skill from running on its own?

level: middleimportance: must knowfreq 27%

basics

~20 s

disable-model-invocation: true stops Claude invoking the skill and drops its description from context, while you can still type /deploy. user-invocable: false only hides it from you; Claude can still load it. /deploy needs the first.

open as a page

In Claude Code, how do you write a skill's description so Claude loads the skill on the requests it should, and only those?

level: middleimportance: must knowfreq 22%

basics

~20 s

Lead the description with what the skill does and when to use it, in the words users actually type; Claude matches requests against the listed description plus when_to_use, cut at 1,536 characters by default, never against the body.

open as a page

In Claude Code, a db-migrations skill exists in both ~/.claude/skills and the repo's .claude/skills — which one runs, and why?

level: middleimportance: should knowfreq 14%

basics

~10 s

The personal one: on a name clash Claude Code ranks enterprise over personal and personal over project, so /db-migrations runs the copy in ~/.claude/skills. Plugin skills never collide because they are namespaced as /plugin-name:skill-name.

open as a page

When you run /fix-issue 123 high in Claude Code, how do $ARGUMENTS, $0, $1 and named arguments in the skill's SKILL.md get filled?

level: middleimportance: should knowfreq 17%

basics

~20 s

$ARGUMENTS becomes the whole string as typed, $0 and $1 take the first and second shell-quoted words, and names declared in the arguments frontmatter map to positions in order. Input no placeholder receives is appended as ARGUMENTS: <value>.

open as a page

A Claude Code skill says to run a spec check after each edit, yet Claude does it once — fix the skill or add a hook?

level: middleimportance: should knowfreq 14%

basics

~20 s

If the check must run after every edit, use a hook: a skill is read once and applied with judgement, while a hook fires on its event every time. Rewording the skill suits judgement calls only.

open as a page

A Claude Code skill sets context: fork with agent: Explore — what does the forked run see, and when does that design backfire?

level: seniorimportance: should knowfreq 9%

basics

~20 s

A new Explore subagent starts with the SKILL.md content as its task and no conversation history; Explore also skips CLAUDE.md and git status. It backfires for reference-only skills and for tasks that depend on what was discussed.

open as a page

A Claude Code skill sets allowed-tools: Bash(gh *) in its frontmatter — what does that grant, for how long, and what does it not do?

level: seniorimportance: should knowfreq 12%

basics

~20 s

It pre-approves matching gh commands only during the turn that invokes the skill; the grant clears at your next message. It restricts no other tool, deny and ask rules still win, and workspace trust does not gate it.

open as a page

In a Claude Code SKILL.md, what does a line like !`git status --short` do, and when does it abort the skill or get disabled?

level: seniorimportance: should knowfreq 10%

basics

~20 s

Claude Code runs the command before the skill reaches Claude and inlines its output, so Claude sees data. A failing command, a deny rule, or outside auto mode any check short of allow aborts the invocation; disableSkillShellExecution swaps in a placeholder.

open as a page

A Claude Code team has forty skills and some never fire despite good descriptions — what is the skill listing budget doing, and how do you fix it?

level: seniorimportance: should knowfreq 9%

basics

~20 s

Claude Code caps the skill listing at 1% of the context window by default; when forty skills overflow it, every name stays but the least-used skills lose their descriptions, so Claude is less likely to pick them. Prune, set name-only, or raise skillListingBudgetFraction.

open as a page

Before adopting a shared Claude Code skill into your project's .claude/skills, what do you review in its folder, and why?

level: seniorimportance: should knowfreq 7%

basics

~20 s

Read it as code that can run: its allowed-tools grants, injected shell commands that execute while it renders, hooks that persist all session, bundled scripts, where and on what model it runs, its name, and whether a side-effecting skill sets disable-model-invocation.

open as a page

Your Claude Code migration skill sets model, effort and a hooks entry in its frontmatter — how long does each apply after invocation?

level: seniorimportance: nice to knowfreq 5%

basics

~20 s

model applies for the rest of the invoking turn and the session model returns at your next prompt; effort applies while the skill is active; hooks register at invocation and keep running for the rest of the session unless a hook sets once: true.

open as a page

In Claude Code, how do skillOverrides and a Skill(deploy) deny rule differ when you must keep Claude from invoking a shared repo's /deploy skill?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

skillOverrides changes what is listed: user-invocable-only hides /deploy from Claude while you can still type it, and off hides it everywhere. A Skill(deploy) deny rule is a permission rule that blocks Claude's Skill tool call itself.

open as a page

How do you prove a Claude Code skill improves results, not just that it triggers, before rolling it out to a team?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

Run the same realistic prompts in fresh sessions with the skill and without it, then compare whether it fired and whether the output improved; the skill-creator plugin automates this for one skill, and claude plugin eval reports the delta for plugin skills.

open as a page