Skip to main content
Claude skill

Commit Message Skill for Claude Code

Reads the staged diff and writes a commit message that says what changed and why. It never commits for you.

By Matthews WongUpdated Checked against Claude Code 2.1.323 docs

Key takeaway

Drop this folder into your skills directory and Claude writes commit messages from what is actually staged. It reads git diff --staged, matches the style of your recent history, keeps one logical change per commit, and writes an imperative subject with a body that explains what and why. It does not invent reasons, and it does not commit or push unless you ask.

2 files

The files

Exactly what the download contains. Read it first, then copy or download.

commit-message/SKILL.md3.2 KB
commit-message/SKILL.md
---
name: commit-message
description: Writes a git commit message from the staged diff, with an imperative subject line and a body that explains what changed and why. Use when the user asks to write a commit message, describe staged changes, "what should I call this commit", or prepare a commit.
allowed-tools: Bash(git status *) Bash(git diff *) Bash(git log *)
---

# Commit message

Write a commit message for the changes that are staged right now. The message
describes only what the diff shows.

## Steps

1. Run `git status --short` to see what is staged and what is not.
2. Run `git diff --staged` and read all of it. If it is long, run
   `git diff --staged --stat` first, then read the diff file by file.
3. If nothing is staged, say so and stop. Do not stage files yourself.
4. Run `git log -n 10 --oneline` and match the style the repository already
   uses (prefixes such as `feat:` or `fix:`, capitalization, language).
5. Decide whether the staged diff is one logical change. If it mixes
   unrelated changes, say which files belong together and propose one
   message per group. Do not hide two changes behind one subject.
6. Write the message in the format below and show it in a code block.

## Format

```text
<subject line>

<body>

<footer, only if needed>
```

Subject line:

- Imperative mood, as if completing "This commit will ...". Write
  "Add retry to webhook sender", not "Added" or "Adds".
- 50 characters or fewer when possible, never more than 72.
- No period at the end.
- Name the thing that changed, not the file list.
- Keep the prefix style found in step 4. If the history has none, add none.

Body:

- One blank line after the subject.
- Wrap lines at 72 characters.
- Say what changed and why. The diff already shows how.
- State the reason only if the diff, the code comments or the user gave it.
  If the reason is not known, describe the change and ask the user for the
  reason instead of making one up.
- Leave the body out for a change that the subject fully explains, such as
  a typo fix.

Footer:

- Issue references or `BREAKING CHANGE:` notes, only when the user or the
  diff provides them. Never invent an issue number.

## Rules

- Describe only changes present in `git diff --staged`. Unstaged and
  untracked files are not part of this commit.
- Never claim that tests pass, that a bug is fixed or that performance
  improved unless the conversation contains the output that shows it.
- Do not run `git add`, `git commit`, `git commit --amend` or `git push`
  unless the user asks for that action in plain words. Writing the message
  is the whole job.
- If the diff contains something that looks like a secret, a key or a
  password, stop and tell the user before writing anything else.
- No marketing words. "Improve", "enhance" and "refactor" need an object and
  a reason, or a more exact verb.

## What to report

1. The proposed message, in a code block, ready to copy.
2. One line listing the staged files it covers.
3. Any warning: mixed changes, unstaged files that look related, a missing
   reason, or a suspected secret.

## Additional resources

- For good and bad messages side by side, see [examples.md](examples.md).
  Read it when the right wording is not obvious.
commit-message/examples.md2.3 KB
commit-message/examples.md
# Commit message examples

Each pair shows a message to avoid and the message to write instead.

## 1. Vague subject

Bad:

```text
Update files
```

Good:

```text
Reject empty email in signup form

The form accepted a blank email and the API answered with a 500.
Validate the field on the client and return a 422 with a field
error from the API, so the user sees which input to fix.
```

Why: the subject names the behavior that changed, and the body gives the
reason a reader will look for in a year.

## 2. Past tense and a file list

Bad:

```text
Changed user-service.ts and user-service.test.ts
```

Good:

```text
Cache user lookups for the length of a request

The order page loaded the same user once per line item. Keep the
result in a request-scoped map so each user is read once.
```

Why: imperative mood, and the files are already listed by git.

## 3. Two changes in one commit

Bad:

```text
Fix date parsing and add export button
```

Good: say that the staged diff holds two unrelated changes, then propose two
commits.

```text
Parse ISO dates without a timezone as UTC
```

```text
Add CSV export button to the orders table
```

Why: one logical change per commit keeps a revert or a bisect clean.

## 4. An invented reason

Bad:

```text
Increase timeout to 30s to fix the flaky production outage
```

The diff only shows a number changing from 10 to 30. Nothing in it mentions
an outage.

Good:

```text
Raise HTTP client timeout from 10s to 30s
```

Then ask the user for the reason and add it to the body once they give it.

## 5. A claim nobody checked

Bad:

```text
Fix login bug, all tests pass
```

Good:

```text
Compare session tokens in constant time

Replace the string equality check in verifySession with
timingSafeEqual, so the comparison time does not depend on how
many leading characters match.
```

Why: "all tests pass" belongs in the message only when the test output is
in the conversation.

## 6. Matching the repository's prefix style

When `git log` shows prefixes such as these:

```text
feat(blog): add reading time to post cards
fix(api): return 404 for unknown slugs
```

write the new message in the same style:

```text
fix(search): keep the query when the dialog reopens
```

When the history has no prefixes, do not add them.

## 7. A change that needs no body

```text
Fix typo in README install step
```
How to use it

From download to working

Use it when

  • You have staged changes and want a message that a reviewer can understand without opening the diff.
  • Your history is full of subjects such as update or fix and you want one consistent style.
  • You want Claude to write the message but leave the commit itself to you.
  • You tend to stage unrelated changes together and want a warning before they land in one commit.
  1. Unzip into your skills folder

    The archive holds one folder, commit-message. Unzip it into .claude/skills/ in your project so the file sits at .claude/skills/commit-message/SKILL.md, or into ~/.claude/skills/ to use it in every project on your machine.

  2. Check that it is listed

    In Claude Code, ask What skills are available? or open /skills and look for commit-message. If the skills folder did not exist when the session started, run /reload-skills first.

  3. Stage one change, then ask

    Run git add on the files for one logical change. Then type /commit-message, or ask Claude to write a commit message. The skill reads the staged diff and your recent log before it writes anything.

  4. Read the message and the warnings

    You get the message in a code block, the files it covers, and any warning: mixed changes, related files left unstaged, or a reason it could not find. Supply the missing reason, then commit yourself or tell Claude to commit.

  5. Adjust the format to your team

    Edit the Format section of SKILL.md if your team uses another subject length, a required prefix or a ticket footer. Add your own pairs to examples.md so the skill learns your wording.

What is inside

Why it is written this way

It starts from the staged diff, not from memory

The first steps run git status and git diff --staged. The message describes only what those show, so work you discussed but did not stage stays out of it.

A stated format with numbers

Subject in imperative mood, 50 characters when possible and never more than 72, no period. Body wrapped at 72 characters that explains what and why. Stated limits are easier to follow than write a good message.

Rules against invented content

No reason unless the diff, a comment or you supplied it. No issue number unless given. No claim that tests pass without the output in the conversation. When the reason is missing, the skill asks.

Read-only git commands are pre-approved

The allowed-tools line lists git status, git diff and git log, so Claude can run them without a permission prompt during the turn that invokes the skill. git add, git commit and git push are not on the list.

Examples in a separate file

examples.md holds seven good and bad pairs. SKILL.md links to it, and Claude opens it only when the wording is not obvious, so the examples do not load on every use.

Watch for

What goes wrong

  • The skill sees only what is staged. If you forgot to git add a file, the message will not mention it, so read the list of covered files.
  • A skill is guidance, not a lock. To block commits or pushes outright, use a permission deny rule or a hook.
  • It can describe what changed from the diff, but the why often lives in your head. Expect it to ask, and answer instead of accepting a guess.
Questions

Frequently asked

Short answers before you download it.

Does the skill run git commit for me?

No. Its instructions tell Claude not to run git add, git commit or git push unless you ask for that action in plain words, and its allowed-tools line pre-approves only git status, git diff and git log. Writing the message is the whole job.

How do I trigger the commit message skill?

Type /commit-message, or ask in plain words, for example write a commit message for the staged changes. Claude matches a request to a skill by its description, and this one names the phrases people use for that task.

Does it follow Conventional Commits?

It follows your repository. The skill reads the last ten commits and keeps the prefix style it finds, such as feat: or fix:. If the history has no prefixes it adds none. To require a prefix, edit the Format section of SKILL.md.

What happens when I staged two unrelated changes?

The skill says so, tells you which files belong together, and proposes one message per group. It does not unstage anything; you split the commit yourself. One logical change per commit keeps a later revert clean.

Go deeper

Learn what this file packages

Free lessons and articles on this site that explain the ideas behind it.

Sources

Primary sources checked on the research date. Follow them for the current version.

More from the toolkit

Take these too

Claude skillFree

Claude Skill Template (SKILL.md)

An annotated SKILL.md to fill in, plus a reference file that shows how to keep the main file short.

  • Claude Code
  • Agent Skills format

2 files3.2 KB.zip

Claude skillFree

Pull Request Description Skill for Claude Code

Reads the branch diff and fills a PR template: why, what changed, real test results, risks and rollback.

  • Claude Code
  • Git

2 files5.8 KB.zip

TemplateFree

CLAUDE.md Template for Any Repository

A 70-line starter CLAUDE.md: project, stack, commands, hard rules, how to verify work and what not to do.

  • Claude Code

1 file2.1 KB.md

All toolkit items