When to use this
- Staged changes are ready to commit and need a message.
- Cleaning up a messy WIP commit history before merging (with an interactive rebase, if the workflow allows it).
- Not for auto-committing without the user's review -- always surface the message before committing, per standard commit safety practice.
The skill file
Copy this verbatim. It's written in the SKILL.md format (YAML frontmatter + markdown instructions) that Claude Code, and increasingly other agent tools, read directly.
---
name: commit-message-writer
description: Write a commit message for staged changes that explains the reasoning behind the change, following the repository's existing commit message conventions. Use when changes are staged and ready to commit, not as a substitute for reviewing the diff first.
---
# Commit Message Writer
## Gather context first
1. `git diff --staged` (and unstaged, to check nothing relevant was
missed) to see exactly what changed.
2. `git log --oneline -10` to match this repo's existing style: sentence
case or lowercase, conventional-commits prefix (`fix:`, `feat:`) or
plain, present vs. past tense, typical length.
## Writing the message
- **Subject line**: what changed, imperative mood ("add," not "added"),
under ~72 characters, no trailing period.
- **Body** (when the change isn't self-explanatory from the subject):
explain *why*, not *what* -- the diff already shows what changed. Cover
the reasoning, the problem being solved, or the trade-off made, not a
line-by-line restatement.
- Reference an issue/ticket number if the repo's convention expects one.
## What to avoid
- Restating the diff ("changed X to Y") without the reasoning behind it.
- Committing unrelated changes together -- if the staged diff covers two
unrelated things, say so and suggest splitting into two commits rather
than writing one message that tries to cover both.
- Inventing a rationale you don't actually have evidence for from the
diff or conversation -- if the "why" isn't clear, ask rather than guess.
## Output
The commit message text, ready to use, matching this repo's established
style.
Installing it elsewhere
The frontmatter/body split above is Claude Code's convention. Here's how to carry the same instructions into other tools:
Save the file below verbatim (frontmatter included) at that path, project-local or in ~/.claude/skills/ for a user-level skill. Claude Code loads the name/description pair to decide when to pull it in, or you invoke it directly as /commit-message-writer.
Convert the YAML frontmatter to Cursor's rule format (description, globs, alwaysApply: false) and keep the markdown body as the rule content. Cursor surfaces it by description match, same idea as Claude Code's auto-load.
Codex CLI (and increasingly other agentic CLIs) read AGENTS.md at the repo root as always-on instructions. Paste the markdown body under a heading like ## {title}; for GitHub Copilot's coding agent, the equivalent file is .github/copilot-instructions.md.
Append the markdown body to .windsurfrules at the repo root. Windsurf treats the whole file as always-on context, so keep only the instructions you want applied on every request.
- Writing "why" content that's actually just "what" restated in prose form.
- Matching a style from general convention (e.g. always using Conventional Commits) instead of this specific repo's actual history.
- Committing without showing the message for review first, when the user hasn't explicitly authorized autonomous commits.