Write your first Claude Code skill

A skill is a folder with a SKILL.md file that teaches Claude Code how to do one particular job: review a pull request, write release notes, explain an error. Instead of retyping a long prompt, you write the instructions once and reuse them.

You can run a skill yourself with a slash command (for example /pr-reviewer), and Claude can also pick it up automatically when your request matches the skill's description.

This recipe builds one from scratch. It assumes Claude Code is already installed.

What you'll build

A skill called commit-message-writer that reads your staged Git changes and proposes a good commit message. (A commit message is the short note that describes a saved set of changes in Git.)

Step 1: Choose where it lives

Skills live in a folder named after the skill, with a file called SKILL.md inside. Where you put that folder decides who can use it:

For this recipe, use the personal location so it works everywhere. (The ~ means your home folder.)

mkdir -p ~/.claude/skills/commit-message-writer

Step 2: Write SKILL.md

A SKILL.md has two parts: a block of settings at the top between --- lines (called frontmatter), then instructions in plain Markdown.

Create ~/.claude/skills/commit-message-writer/SKILL.md with this content:

---
name: commit-message-writer
description: Writes a commit message for the currently staged changes. Use when the user asks for a commit message or wants help describing their changes.
disable-model-invocation: true
---

Run `git diff --staged` and read the result.

Write a commit message in this shape:

- A subject line of 50 characters or fewer, in the imperative ("Add", "Fix", "Remove").
- A blank line.
- A short body explaining why the change was made, not just what changed.

Show the message and ask before committing. If nothing is staged, say so and stop.

Here's what each part does:

• name: the skill's name, which becomes the slash command. If you leave it out, the folder name is used.
• description: what the skill does and when to use it. Claude reads this to decide whether a skill fits your request, so make it specific.
• disable-model-invocation: true: stops Claude from running the skill on its own. It only runs when you type /commit-message-writer. That's a sensible choice for anything that has side effects, like committing code.
• The body: ordinary instructions, written as if briefing a colleague.

According to Anthropic's docs, all frontmatter fields are optional, but a description is recommended.

Step 3: Try it

1. Open a project that uses Git.
2. Make a small change and stage it with git add <file>.
3. Start claude in that folder.
4. Type /commit-message-writer.

Claude runs git diff --staged, reads the changes and shows you a proposed message. Edits to files under ~/.claude/skills/ are picked up while Claude Code is running, so you can tweak the skill and try again without restarting. If you created a brand new top-level skills folder and it doesn't appear, run /reload-skills.

Step 4: Make the instructions better

Skills improve through iteration. After a few runs, notice where the output disappoints and tighten the instructions. Some patterns that help:

Be concrete about the output. "Write a good message" is vague. "Subject of 50 characters or fewer, imperative mood" is checkable.

Say what not to do. "Don't mention file names in the subject" prevents a common annoyance.

Give an example. One short sample of a good result teaches more than a paragraph of description:

## Example

Subject: Add retry to the payment webhook

Body: Stripe occasionally returns a 503. Retrying twice avoids
losing orders without hammering the API.

Tell it when to stop. "If nothing is staged, say so and stop" avoids it wandering off.

Step 5: Add arguments

Skills can take input. In the body, $ARGUMENTS is replaced by whatever you type after the command. You can also add an argument-hint in the frontmatter so the autocomplete menu tells you what to type.

Here's a changelog skill that takes a starting point:

---
name: changelog-writer
description: Drafts release notes from recent git commits.
disable-model-invocation: true
argument-hint: [since-tag-or-date]
---

Run `git log` since $ARGUMENTS (if none is given, since the latest tag).

Group the changes under New, Improved and Fixed. Skip any empty group.
Write each item as one plain-English sentence about what a user will notice.

Show the draft. Do not edit CHANGELOG.md until the user approves.

Run it as /changelog-writer v1.2.0 and Claude uses v1.2.0 where $ARGUMENTS appears.

Step 6: Let Claude trigger it automatically (optional)

If you leave out disable-model-invocation, Claude can load the skill by itself when your request matches the description. That's useful for read-only helpers like an error explainer:

---
name: error-explainer
description: Explains error messages and stack traces in plain English. Use when the user pastes an error, says something is broken, or asks what a message means.
---

When the user shares an error:

1. What it means, in one sentence of everyday language.
2. The likely cause. Check the project's files, don't just guess.
3. The smallest fix to try first, with the exact command or edit.

The description does the work here. Notice it says both what the skill does and when to use it.

Step 7: Add supporting files

SKILL.md is the only required file, but a skill folder can hold others: a longer reference doc, example outputs, even scripts. Mention them in SKILL.md so Claude knows when to read them:

commit-message-writer/
├── SKILL.md
└── examples.md

In SKILL.md: "For more examples of good messages, read examples.md." Anthropic suggests keeping SKILL.md itself under 500 lines and moving detail into supporting files.

Step 8: Share with your team

Move the skill folder into your project's .claude/skills/ directory and commit it. Everyone who opens the project in Claude Code gets the skill. Keep personal-taste skills in ~/.claude/skills/ instead.

Our skills library has ready-made examples you can copy and adapt.

Troubleshooting

The slash command doesn't show up. Check that the folder structure is exactly skills/<name>/SKILL.md and the file is named in capitals. For a newly created top-level skills folder, run /reload-skills.

Claude runs it when I don't want it to. Add disable-model-invocation: true.

Claude never uses it automatically. Make the description more specific about when to use it, and mention the phrases people actually type.

The result is inconsistent. Add an example and tighten the steps. Replace "be thorough" with specifics.

Safety notes

Skills are instructions Claude follows, so treat them like code. Read any skill you download before you install it, particularly if it tells Claude to run commands. Only grant extra permissions you understand, and keep anything that publishes, deletes or spends money behind a manual command.

Recap

1. Make a folder: ~/.claude/skills/<name>/ (or .claude/skills/<name>/ for a project).
2. Write SKILL.md with a name, a clear description and plain instructions.
3. Run it with /<name>.
4. Iterate: add examples, arguments and supporting files.

Once you've written one, you'll start spotting jobs you repeat every week, and each of those is a candidate for a skill.