skip to content

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.