How to Write Claude Code Skills That Actually Fire

1. What a skill actually is (30 seconds)

A skill is a directory with instructions, centered on a single SKILL.md file. How it differs from the three old ways:

Approach	Problem	Skills solve it by
Typing instructions every time	Same request repeated dozens of times, drifting versions	Write once, effective forever
Putting rules in CLAUDE.md	All rules resident in context, interfering, burning tokens	Loading on demand
MCP tools	Adds capability, not method	A skill is the method: steps, standards, prohibitions

One line: MCP gives Claude new hands; a skill teaches it a new brain.

2. Anatomy of a SKILL.md

my-skill/
└── SKILL.md

Two parts: frontmatter (machine-read) + body (read when Claude works).

---
name: code-review-checklist
description: Seven-dimension systematic review of code changes. MUST USE when the user asks to review code, review a PR, check a diff, or says "does this look right".
---

# Code Review Checklist
## Workflow
1. Read the full diff first; understand intent before finding faults
2. Check seven dimensions in order: correctness / security / performance / contracts / error handling / tests / maintainability
3. Every finding must carry file:line and a concrete fix
## Output
Grouped as Blockers / Should-fix / Nits, ending with a Verdict
## Anti-patterns
- Never rubber-stamp with "Looks good"
- Never let style nits occupy a Blocker slot

3. The line that decides everything: description

Claude does not load your skill body by default. It reads each skill's description to decide whether to use it right now. A weak description means your beautiful body text sleeps forever.

The formula

description: [what it does] + [MUST USE when trigger scenarios] + [the exact words users say]

Side by side

❌ Sleeps forever	✅ Fires
`Helps with code quality`	`Seven-dimension review of code changes. MUST USE when the user asks to review, check a PR, look at a diff, or asks "is this code okay"`
`Git commit helper`	`Split logical commits with conventional messages. MUST USE when the user commits code, writes a commit, or says "commit this"`

Write the user's literal phrasing. Nobody says "please optimize my commit craftsmanship" — they say "commit this". Bilingual users? Put both languages' keywords in.

4. The golden body structure

Workflow — numbered steps. Claude follows numbered steps with far higher consistency than prose.
Output — dictate the output shape (ranking / table / required fields). Dictating the shape sets a quality floor.
Anti-patterns — prohibitions. The section most people skip and the highest-leverage one: models obey "never do X" extremely well because it turns fuzzy "be good" into a decidable rule.

"Never approve with only LGTM" beats "be thorough" by an order of magnitude.

5. The seven common mistakes

#	Mistake	Fix
1	Vague description ("improve coding")	Apply the §3 formula; include user phrasing
2	One skill does five jobs	Split it. Narrower trigger = higher hit rate
3	Body is a prompt dump, no steps	Convert to a numbered Workflow
4	No output format contract	Require ranking/tables/fields
5	No Anti-patterns section	Write at least 2-3 hard prohibitions
6	Keywords in one language only	Both languages (the same person says "review" and "审查")
7	Shipping untested	Next section: three test cases

6. How to test: three cases

Trigger test — in a fresh session, make the request using the user's literal phrasing (e.g. take a look at my changes, anything wrong?). Skill doesn't load → rewrite the description.
Negative test — say something adjacent that should NOT trigger ("build me a new feature") and confirm it stays quiet. False fires are worse than misses.
Quality test — plant a bug (say, a missing idempotency check) and see if the skill's Workflow catches it. If not, the steps aren't specific enough.

7. Where to install

# User-level (available in every project)
my-skill/SKILL.md  →  ~/.claude/skills/my-skill/SKILL.md

# Project-level (travels with the repo, shared with the team)
my-skill/SKILL.md  →  <repo>/.claude/skills/my-skill/SKILL.md

Project-level is the team-alignment play: the skill enters the repo, and every teammate's Claude syncs automatically.

8. Want working examples?

These principles come from a 15-skill engineering pack — pr-reviewer / bug-hunter / test-forge / feature-spec / commit-craft are free under MIT and work as copyable templates:

Claude Skills Pro — 15 skills encoding staff-engineer workflows

Free samples on GitHub (MIT) Full catalog →