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
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.
Exactly what the download contains. Read it first, then copy or download.
---
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
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
```
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.
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.
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.
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.
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.
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.
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.
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.
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.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.
Short answers before you download it.
Free lessons and articles on this site that explain the ideas behind it.
Primary sources checked on the research date. Follow them for the current version.
An annotated SKILL.md to fill in, plus a reference file that shows how to keep the main file short.
2 files3.2 KB.zip
Reads the branch diff and fills a PR template: why, what changed, real test results, risks and rollback.
2 files5.8 KB.zip
A 70-line starter CLAUDE.md: project, stack, commands, hard rules, how to verify work and what not to do.
1 file2.1 KB.md