SKILL.md walkthrough

Build your own Claude Code skill

A skill is a 20-80 line markdown file with YAML frontmatter. Here's how to write one that doesn't need rewriting two weeks later.

Walkthrough verified April 21, 2026

The short answer

A Claude Code skill is a markdown file with YAML frontmatter (description: is the only required field) and a body of plain-English instructions. Write it like a playbook for a competent colleague: purpose, when-to-use, numbered steps, output format, failure modes. Test with three passes — dry-run, happy path, edge case — then ship.

Rule of three

Skills are cheap but not free. They add files to maintain and slash commands to remember. Only write a skill when you've typed the same instructions three times.

The pattern:

• Once: just prompt it.
• Twice: maybe copy the prompt into a note.
• Three times: write the skill.
• Five times in a week: promote to a subagent with its own tools.

Frontmatter fields

Only description is required. Every other field is a tool, not a tax.

Field	Required	What it does
description	Required	One-line plain-English summary of what the skill does. Claude Code shows this in autocomplete.
allowed-tools	Optional	Array of tool names the skill can use (e.g. [Bash, Read, Edit]). Omit to allow all tools.
model	Optional	Force a specific Claude model — 'claude-haiku-4-5' for lightweight tasks, 'claude-opus-4-7' for deep reasoning.
argument-hint	Optional	What input, if any, the skill expects. Shown in autocomplete after the slash command.

Body structure

Five sections, in this order. Most skills don't need all five — but the ones that earn their keep have at least three.

1
Purpose (1 sentence)
What this skill does, not how. Skip to step 2 if the description frontmatter already covers it.
2
When to use
Two or three sentences on the trigger conditions — what problem does this solve, and when does it NOT apply.
3
Steps
Numbered, specific, and skippable. Each step should produce a checkable outcome. Think 'run git status, check branch, if dirty then stage'.
4
Output format
Tell Claude the shape of the reply — a table? bullet list? commit message? Without this, output wanders.
5
Failure modes
What the skill should do when it encounters unexpected state. 'If tests fail, report the failure and stop — do not --no-verify.'

Copy-paste template

Drop this into ~/.claude/commands/<your-skill>.md and fill in the blanks. The comments show what each block does.

---
description: One-line summary of what this skill does (shown in autocomplete).
allowed-tools: [Bash, Read, Edit, Grep]  # optional — restrict tool access
argument-hint: <file-path>                # optional — shown after /<name> in UI
---

# <Skill Name>

## Purpose

One sentence on what this skill does. Skip if the frontmatter description already covers it.

## When to use it

Two or three sentences on the trigger conditions. What problem does this solve?
When does this NOT apply?

## Steps

1. Run <command A>. If output is X, stop and report.
2. Read <file>. Extract <specific thing>.
3. Run <command B> with <extracted thing>.
4. If <condition>, do <action>. Otherwise, do <other action>.

## Output format

Report back in this shape:

```
Finding 1: <summary>
Finding 2: <summary>
Recommendation: <single sentence>
```

## Failure modes

- If <tool> is not installed, report the missing dependency and stop.
- If <file> does not exist, report and stop — do not create it.
- Do not use --no-verify or skip steps silently.

Testing loop

Three passes before you trust a new skill with real work.

Pass 1 — Dry-run

Run the skill with a note: "describe what you'd do without running anything". Check the steps match your intent. Catches wrong order, missing checks, skipped validation.

Pass 2 — Happy path

Run on a normal input. Compare output format against what you specified. Common issue: Claude drops the output-format section when the input is simple.

Pass 3 — Edge case

Feed it something weird — empty file, huge file, missing dependency, conflicting state. The skill should fail loudly, not silently skip steps. If it papers over the problem, add an explicit failure-mode instruction.

Checklist before you save

☐Frontmatter valid YAML? A broken description: silently drops the skill from autocomplete.
☐Description under 100 chars? Longer and it wraps in autocomplete.
☐Steps numbered and specific? 'Run tests' is a bug; 'run npm test -- --coverage and report failures by file' is a skill.
☐Failure modes spelled out? Especially for anything that mutates state (commit, push, deploy, delete).
☐Output format specified? 'Report back' is vague — pick a shape.
☐No hardcoded secrets? Skills live in dotfiles that often get pushed. Read twice.
☐Attribution preserved if forked? MIT and Apache-2.0 require the original copyright notice in redistributions.

Patterns worth copying

Skills in the catalogue that show these patterns well — open and read the source to pick up the style.

SKILL.md Template

The canonical SKILL.md template from Anthropic's official skills repo — frontmatter fields, trigger syntax, invocation patterns.

Commit Helper

Stages relevant changes, writes a conventional-commit message, and pushes — in one command.

Drift Check

Verifies a project's reference data (prices, models, deps) against upstream sources — flags staleness.

Legal Sweep

Audits a site for a legal disclaimer page + footer link; creates and wires up if missing.

Frequently asked

When should I write a skill versus just re-prompting?+

Rule of three: once you've typed the same instructions three times, it's a skill. Until then, just prompt. Skills are cheap to write but non-zero — they add files to maintain, slash commands to remember, and review overhead. The break-even is usually around task #3 or #4 of the same kind.

Slash command, subagent, or bundled skill — which one?+

Slash command (~/.claude/commands/) for a named prompt you invoke manually — 80% of skills fit here. Subagent (~/.claude/agents/) when you want Claude to delegate to a specialist with a fresh context window and narrow tools. Bundled skill (~/.claude/skills/<name>/) when the workflow needs scripts, helper files, or multi-file templates. Start as a slash command; graduate later.

What goes in the frontmatter?+

Minimum: description (what the skill does, in one sentence). Optional: allowed-tools (restrict which tools the skill can use), model (force a specific Claude model, useful for Haiku-only light tasks), and name (defaults to filename). Keep frontmatter tight — everything the skill's body can say, let it say.

How long should a skill be?+

Shorter than you think. 20-80 lines of markdown covers most real skills. If yours hits 200 lines, it's probably doing two jobs — split it. The best skills read like instructions to a competent colleague: 'run X, check Y, if Z then do W, report back in this format.'

How do I test a skill before trusting it?+

Three-pass test: dry-run (tell Claude to describe what it would do without executing), happy-path run, edge-case run. For each, check the output format and that Claude didn't skip steps. A skill that silently drops steps 3-5 when the input is unusual is worse than no skill.

Should I version-control my skills?+

Yes — keep ~/.claude/ or a mirror repo under git. It's rare to regret pushing, common to lose skills to an accidental rm. For shareable skills, publish to a public GitHub repo with an MIT licence and link-friendly frontmatter. For stack-specific ones, commit them into the project's .claude/ directory so the team inherits them.

Can I ship a skill to this catalogue?+

Not via form submission yet — this is a curated directory. If you want your skill considered: publish it on GitHub with an MIT or Apache-2.0 licence, let it mature for 30+ days with at least one real-world use case, and mention @bryanjcollins on X with a link. Criteria: clear licence, real workflow (not a stub), not a duplicate.

Browse the catalogue for inspiration

57 skills across 10 categories — all licence-verified, all open to forking and adapting.

Browse 57 skills Install guide