How to set up Claude Code skills

The five-minute version

A skill is a named procedure you can call by name, and that Claude can reach for on its own when the moment matches. It is one file:

mkdir -p .claude/skills/ship-check
$EDITOR .claude/skills/ship-check/SKILL.md

Then, inside that file:

---
name: ship-check
description: Pre-commit gate. Run tests, lint and type check; report PASS/FAIL
  per step and anything that could not run. Use before any commit or PR.
---

1. Read `CLAUDE.md` for the test / lint / typecheck commands.
2. Run each one. Capture the exit code and the last 20 lines of output.
3. Report a table: Step | PASS/FAIL | detail. A step that couldn't run is FAIL,
   never skipped silently.
4. If anything failed, say what to fix first. Don't fix it unless asked.

Start a session in that repo and type /ship-check. That is the whole mechanism. Everything below is the part people get wrong on the second one.

Where the file goes, and what that changes

The folder name is the command. .claude/skills/deploy-staging/ gives you /deploy-staging. The name: field in the frontmatter is a display name — renaming it does not rename the command, which is worth knowing before you spend ten minutes wondering why /my-nice-name is not found.

The description field is the whole game

Every frontmatter field is optional. description is the one that matters, because it is not a label — it is the trigger. Claude reads it to decide whether to apply the skill without being asked.

So write it as when, not what:

The first column is what a person would name a file. The second is what someone would say when they want it. Write the second and the skill starts showing up on its own.

While you are tuning it, you can always invoke a skill directly by name as a slash command — the two paths are independent, so a skill that never auto-fires is still perfectly usable.

The fields worth knowing about

A skill can also be a folder rather than a lone file: put reference.md or scripts/helper.sh beside SKILL.md and refer to them from the steps. That is usually the right move once a skill's instructions pass a screenful.

What skills do not fix

Three things get confused constantly, and only one of them is a skill:

• A skill is a procedure — run when called, or when the description matches.
• A hook is a command your machine runs on an event, whether Claude wants it or not. A formatter after every edit is a hook, not a skill.
• A permission allowlist in .claude/settings.json is what stops the “can I run npm test?” prompt for the fortieth time.

If your complaint is “it asks permission for everything”, no skill will fix it — that is the allowlist: Claude Code keeps asking permission. If it is “it re-learns my repo every session”, that is CLAUDE.md: Claude Code forgets my project.

How to tell it is actually working

• It appears by name. Type / and look for the folder name. Missing means the path or the filename is wrong — it is SKILL.md, capitalised, inside a folder named for the command.
• It fires unprompted. Describe the situation in your own words without naming the skill. If nothing happens, the description is a label, not a trigger.
• It reports rather than hides. A step that could not run should come back FAIL, not be skipped silently. Write that into the skill, because the default is whatever the model feels like.

Copy a working set, free

The ship-check skill above is not an illustration — it is the real file from our free starter repo, MIT licensed. The repo also ships new-feature and explain-diff, a .claude/settings.json with the allow and deny lists already filled in, a CLAUDE.md to copy, and a formatter hook. No dependencies, no telemetry. Read the whole thing in five minutes.

Want the same three skills as installable plugins instead of copied files? kit-plugins, also free.

If you would rather not write them yourself

Free first — the starter above is a complete setup and costs nothing. Two paid rungs exist for the two reasons people give up on doing it themselves:

Clocks run from a complete intake, not from the Stripe receipt. We use AI tools including Claude to produce the work, and a person reviews every deliverable before it ships.