How to write a Claude Code skill that actually helps
A Claude Code skill is a folder with one Markdown file in it. Writing one takes ten minutes. Writing one that makes Claude's output better instead of worse takes a few rules most public skills ignore.
This guide covers what a skill is, where it goes, how Claude decides to use it, and how to write the instructions so they change behavior. At the end there's a complete skill you can copy into your setup today.
What a skill is
A skill is a directory containing a SKILL.md file. The file starts with a short front matter block, then plain Markdown instructions:
---
name: commit-message
description: Write a commit message for the staged changes. Use when asked to "commit", "write a commit message" or before running git commit.
---
# Write a commit message
...your instructions...The folder can also hold scripts, templates or reference files that the instructions point to. Claude reads them only when the skill tells it to, so you can ship a long checklist or an example without bloating every conversation.
Where skills live
- Personal skills go in
~/.claude/skills/<name>/SKILL.mdand are available in every project. - Project skills go in
.claude/skills/<name>/SKILL.mdinside a repo. Commit them and your whole team gets the same workflow.
Use project skills for anything tied to one codebase (its deploy steps, its review rules). Use personal skills for how you like to work everywhere.
How Claude decides to use a skill
Claude doesn't read every skill in full at the start of a session. It sees each skill's name and description, and loads the full instructions only when a request matches. You can also call a skill directly by typing / followed by its name.
That makes the description the most important line in the file. It has to say two things: what the skill does, and when to use it, in the words people actually type.
# Too vague: Claude can't tell when this applies
description: Helps with code quality.
# Clear job, real trigger phrases
description: Review the current branch or a PR number for real bugs before merge.
Use when asked to "review", "check my PR" or "look over this diff".Five rules for skills that help
1. Write a procedure, not a personality
"You are a world-class senior engineer" changes very little. A numbered list of steps changes a lot: what to read first, what to run, what to check, in what order. Good skills read like the checklist an experienced colleague follows without thinking.
2. Tell it how to find the input
Most bad output starts with Claude working on the wrong thing. Spell out where the input comes from: "a PR number in the request, otherwise the current branch against origin/main, plus uncommitted changes." Include the commands. Claude is good at running git and gh, but only if it knows which ones you mean.
3. Make it verify before it reports
The biggest difference between a useful skill and a noisy one is a verification step. Before a finding, a fix or a claim goes in the answer, the skill should make Claude try to prove it wrong: trace a concrete input that triggers it, run the test, check whether something upstream already handles it. Anything that doesn't survive gets dropped. This one step removes most of the false positives that make AI output tiring to read.
4. Pin down the output
Show the exact shape of the answer with an example: a verdict line first, then findings with file and line, severity, and evidence. Say what to leave out too. "Don't praise, don't summarize the diff back, don't list what you checked" saves your reader more time than any other line in the file.
5. Say what not to do
Every skill has a failure mode it keeps sliding toward. A debugging skill wants to add retries and sleeps. A refactoring skill wants to change behavior while it tidies. Name the shortcut and ban it: "No retries, sleeps or skipped tests. Fix the cause."
Test it like code
Pick three real tasks from the last month. Run each one with the skill and without it, in the same repo. If the output with the skill isn't clearly better on at least two of them, the skill isn't done. Usually the fix is a sharper description, a missing step, or a tighter output format, not more words.
Keep the file short enough that you'd read it yourself. If it grows past a page or two, move the reference material into a separate file in the skill folder and link to it from the steps that need it.
A free skill to copy
Here's a complete skill that writes commit messages from the staged diff. Save it as ~/.claude/skills/commit-message/SKILL.md:
---
name: commit-message
description: Write a commit message for the staged changes. Use when asked to
"commit", "write a commit message", or before running git commit.
---
# Write a commit message
## 1. Read the change
- Run `git diff --staged`. If it's empty, say so and stop.
- Run `git log -10 --oneline` and match the repo's style (prefixes like
"feat:", ticket ids, capitalization, tense).
## 2. Work out why
- Name the one user-visible or developer-visible effect of the change.
- If the staged diff mixes unrelated changes, say so and suggest how to
split it instead of writing one vague message.
## 3. Write it
- Subject: imperative mood, under 60 characters, says what changes,
not which files ("Retry failed webhook deliveries", not "Update webhook.ts").
- Body (only if the why isn't obvious): 1-3 short lines on the reason
and any behavior change a reviewer must know about.
- Never invent context you can't see in the diff, like ticket numbers.
## 4. Check before you commit
- Re-read the diff once against the message. Remove any claim the diff
doesn't support.
- Show the message and ask before running `git commit`, unless the user
already asked you to commit.Try it on your next commit. Then compare the five rules above against any skill you already use; most can be fixed in a few minutes.