← All skills

Writing Commit Messages

Writes Conventional Commits messages from a staged diff, explaining why a change was made rather than restating what it changed. Use when the user asks for a commit message, mentions committing, or shares a diff and asks how to describe it.

Skill name
writing-commit-messages
Category
coding
Price
Free
Install
~/.claude/skills/writing-commit-messages/SKILL.md
Tags
git, commits, conventional commits, changelog

Writing Commit Messages

The subject line is read in git log, in blame, and in a release note. The body is read once, by whoever is bisecting a production incident at 2am and needs to know why this change existed.

Format

type(scope): imperative summary under 72 characters

Why the change was needed. What was happening before, what happens now.
Keep it to the reasoning a reader could not recover from the diff.

Refs: #1284

Types: feat, fix, refactor, perf, docs, test, build, ci, chore. A breaking change gets ! after the scope and a BREAKING CHANGE: paragraph.

The one rule

The diff already says what changed. The message says why. If the body could be reconstructed by reading the diff, it is not earning its space.

Examples

Input: added a token check to the login handler.

feat(auth): validate JWT audience on login

Tokens minted for the staging audience were accepted in production
because only the signature was checked. Both environments share a
signing key, so this let a staging token authenticate here.

Input: changed a retry count from 5 to 3.

fix(sync): reduce retries to 3 to stay inside the 30s gateway timeout

Five retries with backoff reached 41s worst case, so the gateway cut
the connection and the client saw a 504 rather than the real error.

Input: renamed variables and reordered functions, no behaviour change.

refactor(parser): group token handlers by node type

No behaviour change. Preparation for the block-quote handler, which
needs to dispatch on node type rather than on character.

Working from a diff

  1. Identify the single reason this change exists. If there are two, it is two

commits.

  1. Pick the type from that reason, not from the file types touched.
  2. Scope is the area a reader would search for — usually a module or a feature.
  3. Write the subject in the imperative: "add", not "added" or "adds".
  4. Write the body only if the reason is not obvious from the subject, and note

anything a reader would be surprised by — a workaround, a temporary fix, a deliberate omission.

Avoid