Claude Code Skill Examples: 10 Real SKILL.md Files, Annotated

The fastest way to learn the SKILL.md format is to read working skills. This page walks through ten real SKILL.md files from this directory, each picked because it shows one technique well: a description that triggers, a checklist, a decision table with numbers, an on-demand reference file, a bundled script, a verification step, a gotchas section, a non-coding skill, a document skill, and a Claude Code meta skill. Every excerpt is copied verbatim from the skill’s file, and each skill name links to its page, where you can read the whole thing and install it.

At the end there is a minimal template you can copy into .claude/skills/<name>/SKILL.md to start your own.

1. A description that triggers: commit-craft

Claude reads only the name and description of every installed skill when it decides what to load. The body is invisible until the description matches. Commit Craft has a description that does the job:

---
name: commit-craft
description: Produces atomic, reviewable git commits with Conventional Commits headers and bodies that explain why, by staging hunks selectively, splitting mixed changes, and folding corrections in with fixup commits and autosquash. Includes a stdlib message linter usable as a commit-msg hook. Use when the user asks to commit changes, write a commit message, split a messy working tree into commits, clean up WIP commits before a PR, or set up conventional commit checks.
license: MIT
---

Why it works: the first sentence states the capability in the third person and names the specific methods (hunks, fixup, autosquash), so Claude can tell this apart from a generic git skill. The “Use when” sentence lists the phrases people actually type, including informal ones like “messy working tree” and “WIP commits”.

2. A numbered workflow with a checklist: systematic-debugging

Long procedures fail in a predictable way: Claude skips the boring middle step. Systematic Debugging opens its workflow with “Copy this checklist into your working notes and tick items as you go,” followed by the list:

- [ ] 1. Capture the exact symptom
- [ ] 2. Reproduce reliably (ideally as a failing test)
- [ ] 3. Narrow the search space
- [ ] 4. Form ranked hypotheses
- [ ] 5. Test hypotheses with minimal experiments
- [ ] 6. Fix the cause, not the symptom
- [ ] 7. Verify and guard against regression
- [ ] 8. Report the root cause

Why it works: a visible checklist turns “remember the procedure” into “finish the list”, and an unticked box is easy to spot for both Claude and you. Each item maps to a numbered section with the detail, and reproduction comes before any fix.

3. A decision table with numbers: connection-pooling

Advice like “keep pools small” leaves Claude to invent a number. Connection Pooling gives it starting values per client library:

Start small. Throughput peaks when active connections roughly equal what the database can
run at once - about `2 x CPU cores` (plus disk parallelism) on the database server, shared
across all clients. Per-process pool max is that budget divided among processes.

| Client | Setting | Default | Starting point |
|---|---|---|---|
| HikariCP (JVM) | `maximumPoolSize`, `minimumIdle` | 10, same as max | 10; set `minimumIdle` = max (fixed pool) |
| node-postgres | `new Pool({ max })` | 10 | 10 per process; `idleTimeoutMillis: 10000`, `connectionTimeoutMillis: 5000` |
| SQLAlchemy | `pool_size`, `max_overflow` | 5, 10 | 5 + 5; `pool_pre_ping=True`, `pool_recycle=1800` |
| Prisma | `connection_limit` URL param | cores x 2 + 1 | explicit value; `pool_timeout` |
| Go database/sql | `SetMaxOpenConns`, `SetMaxIdleConns`, `SetConnMaxLifetime` | unlimited, 2, none | 10-25, same idle, 30 min |
| Django | `CONN_MAX_AGE` (persistent per thread), `OPTIONS: {"pool": True}` on Django 5.1+ with psycopg 3 | 0 (new conn per request) | 60 with health checks, or the psycopg pool |

Why it works: the table puts the rule, the library default, and a concrete starting value side by side, so Claude can see when a project is still on a risky default. The rule above it gives the reasoning (database parallelism, not traffic) in one sentence, which lets Claude adjust the numbers instead of copying them blindly.

4. A reference file loaded on demand: schema-migrations

Some detail matters only for a minority of tasks. Zero-Downtime Migrations keeps the common lock-safe patterns in SKILL.md and moves the full operation-to-lock table into references/lock-matrix.md. The body points to it at the moment it is needed:

The full operation-to-lock table and safe alternatives are in
[references/lock-matrix.md](references/lock-matrix.md). Read it for any operation not
shown above.

The reference file opens by restating when it applies:

Read this when a migration contains an operation not covered in SKILL.md, or when you need
to explain why a statement blocked traffic.

Why it works: the 94-line lock matrix costs nothing until a migration contains an unusual operation, so routine reviews stay lean. The link sits inside the workflow step that needs it, with an explicit condition, rather than in a “see also” list Claude may ignore.

5. A bundled script whose output enters context: csv-cleaning

When a step has one correct answer, a script beats instructions. CSV Cleaning ships scripts/csv_profile.py, a standard-library profiler, and runs it as step 2 with python3 scripts/csv_profile.py data/raw/export.csv. The skill then tells Claude what the output will contain:

The profiler reports encoding and BOM, line endings, the delimiter that gives the most
consistent field count, ragged rows with line numbers, exact duplicates, and per column:
null share, distinct count, inferred types, ambiguous date formats, decimal commas,
thousands separators, whitespace issues, and candidate keys. It exits 1 on structural
problems.

Why it works: Claude runs the script and reads only its report, not its source, so hundreds of lines of detection logic cost a few lines of context. Describing the output in advance tells Claude what to look for and how to act on the exit code. A tested script also gives the same answer every time.

6. A verification step with pass conditions: safe-refactoring

“Double-check your work” is not a check. Safe Refactoring ends with conditions that are either true or false:

## Verification

- Every commit in the series passes tests: `git rebase -i --exec "<test cmd>" origin/main`.
- A deliberately injected bug in moved code is caught by the safety net.
- Diff review shows only moves, renames, and extractions; no logic edits hidden inside.

Earlier, while building the test safety net, it asks for the same kind of proof:

5. Mutation check the net: temporarily break a line in the code to be moved and confirm
   at least one test fails.

Why it works: each line names a command or an observable result, so Claude cannot report success without doing the work. The mutation check tests the tests, which catches the common failure where a green suite never covered the code being moved.

7. A gotchas section: structured-outputs

Gotchas are the facts that look wrong until you have been burned by them. Structured Outputs collects them in one place:

## Gotchas

- First request with a new schema can be slower while the provider compiles the grammar;
  schemas are cached afterwards, so do not generate a new schema per request.
- Free-text fields inside a strict schema still hallucinate. Shape is guaranteed, content
  is not.
- `required` plus no nullable option forces invented values for missing data.
- Large enums (hundreds of labels) hurt accuracy; use a two-stage classify (group, then
  label) or retrieval over label descriptions.
- Long documents with many repeated items (line items, rows) can hit `max_tokens`; check
  the stop reason and chunk the input.

Why it works: each bullet pairs a non-obvious failure with what to do about it, in one or two lines. These are exactly the things Claude would not infer on its own, which is the test for whether a line belongs in a skill at all.

8. A non-coding skill: feature-prioritization

Skills are not only for code. Feature Prioritization encodes how a product team scores a backlog, including rules that stop the scores from drifting:

Calibration rules:

- Pick a reference item everyone knows (a shipped feature) and score it first. Score
  every other impact relative to it.
- If more than half the items are impact 2+, the scale is inflated; re-score.
- If more than half claim 100% confidence, ask for the data behind each.
- Effort under 0.25 person-months inflates scores; floor it at 0.25.
- Reach must use the same window and unit for every item (accounts per quarter, not a
  mix of daily users and total signups).

Why it works: Claude already knows what RICE is, so the skill spends no words on the formula’s history. It spends them on judgment calls a seasoned PM makes, written as checkable thresholds (“more than half”, “0.25 person-months”). The same pattern works for any judgment-heavy job, from research methods to editorial review: turn the expert’s instincts into rules with numbers.

9. A document skill: xlsx-spreadsheets

File-format skills need to warn about what the libraries silently do. Excel Spreadsheets (.xlsx) gives the most important caveat its own section:

## The recalculation caveat

openpyxl and exceljs write formula *text*; they do not calculate. Consequences:

- A file you just wrote has formulas with **no cached values**. Excel calculates them on
  open; but anything reading the file with `data_only=True` (or pandas) sees `None`.
- Loading with `data_only=True` and saving **replaces formulas with their last values**
  permanently. Never save a workbook loaded with `data_only=True` over the original.
- To get computed values without Excel: recalculate with LibreOffice headless (open and
  re-save via a conversion such as `soffice --headless --convert-to xlsx --outdir recalculated/ model.xlsx`),
  then re-run the audit to confirm cached values exist. Alternatively compute the numbers
  in Python and write both the value-based check and the formula.
- Tell the user explicitly when the delivered file has not been recalculated.

Why it works: this one fact prevents both a destroyed workbook and a confident report built on None values. The section gives the workaround next to the warning and ends with an honesty rule, so Claude tells the user what it could not verify. The skill also bundles scripts/xlsx_audit.py, which flags error values and uncalculated formulas before and after every edit.

10. A Claude Code meta skill: hooks-automation

Meta skills teach Claude to configure Claude Code itself. Hooks Automation starts by deciding whether a hook is even the right tool:

## Hook or something else?

| Requirement | Use |
|---|---|
| Must happen every time, no judgment (format, lint, log, block) | **Hook** |
| Simple allow/deny of a tool or command prefix | Permission rule in `permissions` (see `permissions-policy`) |
| Deny that needs parsing (any `rm -rf` anywhere in a pipeline, writes outside `src/`) | **PreToolUse hook** |
| Guidance Claude should weigh | CLAUDE.md or a skill |

Later, it makes testing a required step:

Step 4 is not optional. A hook with a syntax error either blocks every tool call or
silently does nothing:

Why it works: a routing table at the top stops Claude from building a hook when a one-line permission rule would do, and it names the sibling skill to use instead. Calling out the mandatory step, with the reason it is mandatory, keeps Claude from skipping the pipe test. The description also quotes user phrases such as “every time” and “whenever”, so requests phrased as standing rules reach this skill.

Patterns these examples share

Read the ten files side by side and the same structure keeps appearing:

• A definition of done in the first paragraph, such as “A refactor is safe when behavior is provably unchanged”.
• Ground rules Claude would plausibly break without being told.
• A checklist of five to eight steps, each expanded in its own section.
• Tables for decisions and numbers, prose for reasoning.
• Gotchas, verification and an output template as separate sections at the end.

None of them explain basics. They spend their lines on the rules, numbers, and failure modes that general knowledge misses.

A minimal SKILL.md template

Copy this into .claude/skills/your-skill-name/SKILL.md, rename the folder and name to match, and replace every line with your own content. Delete the script and reference lines if you do not need them.

---
name: your-skill-name
description: Does X for Y using Z, and reports A. Use when the user asks to <verb> <thing>, mentions <symptom or phrase>, or before <event>.
---

# Your skill name

The job is done when <one sentence with concrete, checkable outcomes>.

## Ground rules

- <A rule Claude would break without being told.>
- <Follow the repo's existing convention over this skill's defaults.>

## Workflow

Copy this checklist and tick items as you go:

- [ ] 1. <Inspect or gather>
- [ ] 2. <Decide, using the table below>
- [ ] 3. <Do the work>
- [ ] 4. <Verify>
- [ ] 5. <Report>

### 2. Decide

| Situation | Do |
|---|---|
| <case> | <action, with a number if one applies> |

### 3. Do the work

Run `python3 ${CLAUDE_SKILL_DIR}/scripts/check.py <file>` and fix what it reports.
For <rare case>, read [references/details.md](references/details.md) first.

## Gotchas

- <Non-obvious failure>: <what to do instead>.

## Verification

- <Command> exits 0.
- <Observable result> is true.

## Output

**Result:** <one line>
**Changes:** <list>
**Not verified:** <anything you could not check>

The ${CLAUDE_SKILL_DIR} variable points at the skill’s own folder, so the script path works whether the skill is installed per project or in ~/.claude/skills/.

Next steps

• Build one from scratch with testing: Write your first Claude Code skill
• Every frontmatter field and where files go: SKILL.md format reference
• The rules behind these examples: Skill authoring best practices
• Let Claude scaffold and validate a new skill: skill-authoring