Guides

How to write Claude Code skills that actually trigger

A skill is a folder containing a SKILL.md file: packaged instructions that Claude loads when a task matches, or that you invoke with /skill-name. Good skills turn "Claude sometimes does this well" into "Claude does this our way every time".

Where skills live

~/.claude/skills/<name>/SKILL.md     # personal: every project
.claude/skills/<name>/SKILL.md       # project: commit it and your team gets it

A skill folder can also hold supporting files, such as reference docs, examples or scripts. Mention them in SKILL.md and Claude reads them only when needed, which keeps the context small.

Anatomy of SKILL.md

---
name: release-notes
description: Turn git history between two refs into user-facing release notes,
  grouped by impact, with breaking changes called out. Use when cutting a release,
  tagging a version, updating CHANGELOG.md, or asked "what changed since vX".
---

# Release Notes

1. Find the range: `git describe --tags --abbrev=0` .. HEAD
2. Match the existing CHANGELOG format exactly.
3. ...

• name: lowercase with hyphens. It defaults to the folder name, and it's the /command you type.
• description: the most important line. Claude sees every skill's description up front and loads the body only when the description matches the task.
• Optional fields include allowed-tools (pre-approve tools while the skill runs), disable-model-invocation: true (only you can trigger it, for skills with side effects like deploys), and context: fork (run it in an isolated subagent).

Writing descriptions that trigger

Most skills that "don't work" have a vague description. The pattern that works: what it does + when to use it + the words users actually say.

Weak	Strong
Helps with tests.	Write tests that match the project's existing conventions, covering behavior and edge cases. Use when the user asks to add tests, raise coverage, or test a specific function or endpoint.
Database migration helper.	Review schema migrations for locking, data loss and deploy-order hazards. Use when a migration file is added or changed, or the user asks "is this migration safe".

Writing the body

• Tell Claude how to discover things, not what they are. "Find the test command in package.json scripts, Makefile or CI config" works in every repo. "Run npm test" breaks in half of them.
• Put verification in the procedure. "Run the new test, then temporarily break the code and confirm the test fails" is what separates a senior workflow from a checklist.
• Define the output. End with the exact report format you want.
• Say when to stop and ask. For example: before force flags, before destructive migrations, or when a fix needs an architecture change.
• Keep it short. About 60–120 lines is usually right. Move long references into sibling files.

A complete free skill: debug-loop

Copy this into .claude/skills/debug-loop/SKILL.md:

---
name: debug-loop
description: Systematic debugging for bugs that aren't obvious: reproduce first,
  form ranked hypotheses, test them one at a time, and fix the root cause with a
  regression test. Use when a bug resists a quick fix, a test is flaky, or behavior
  differs between environments.
---

# Debug Loop

1. **Reproduce before touching code.** Get the exact command and full error.
   Shrink it to the smallest failing case. For intermittent failures, run it 20x and count.
2. **Read the evidence.** Read the whole stack trace and find the first frame in project
   code. Check `git log -p --since="2 weeks ago"` on suspect files.
3. **List 2–5 hypotheses**, ranked by likelihood x cheapness to test. Each must
   predict something observable.
4. **Test one at a time.** Prefer observation (logging, debugger) over modification.
   If it used to work: `git bisect run <test cmd>`. After three dead ends, re-read step 2.
5. **Fix the root cause.** Explain why the bug happens in 1–2 sentences before editing.
   Write a regression test and confirm it fails before the fix and passes after.
6. **Clean up and report:** root cause, fix, test, and what was ruled out.