---
name: commit-message-writer
description: Writes commit messages from the staged diff with a short imperative subject and a body that explains why, one logical change per commit, matching the repo's existing convention. Use when the user asks to commit, or for a commit message for staged changes.
---

# Commit Message Writer

A commit message tells a future reader what changed and why, so they do not have to reverse-engineer it from the diff. Base it on the real staged changes, never on what you remember doing.

## 1. Read the facts

```bash
git status --short
git diff --staged --stat
git diff --staged
git log --oneline -15
```

If nothing is staged, tell the user and show `git status`; do not stage everything on your own. If unstaged changes exist as well, mention them and ask what belongs in this commit.

## 2. Learn the repo's convention first

Look at `git log` before writing:

- Language of messages (English, Russian, other) and letter case of the subject.
- Prefix style: Conventional Commits (`feat:`, `fix(scope):`), ticket keys (`PROJ-123 ...`), plain sentences, emoji.
- Subject length and tense; presence of bodies and trailers.
- Any written rule in `CONTRIBUTING.md`, `.gitmessage`, or a commit-lint config (`commitlint.config.*`).

Follow what the repo does, even if you prefer another style. If the history is mixed or empty, use a short imperative subject with no prefix.

If the user has stated commit rules (for example no trailers, lowercase subjects), those override your defaults.

## 3. One logical change per commit

Check that the staged diff is a single idea. If it mixes a bug fix, a refactor and a formatting pass, say so and propose a split:

```bash
git reset                    # unstage all, keeps the working tree intact
git add -p path/to/file      # stage hunks of one change
```

Only suggest the split; do the unstaging with the user's agreement, because it changes what they prepared.

## 4. Write the message

Structure:

```
<subject: imperative, about 50 chars, no trailing period>

<body: why this change was needed, wrapped at about 72 columns>
<what behavior changes for users or callers, and anything non-obvious>
<side effects, follow-ups, or alternatives rejected, only if useful>
```

Rules:

- Subject in the imperative mood: "add retry to upload", "fix off-by-one in pager", not "added" or "fixes".
- Subject says what changed at the level of behavior, not the file or function names alone.
- The body explains why: the problem, the cause, the reason for this approach. The diff already shows how.
- Mention breaking changes explicitly, and issue or ticket references in the form the repo uses (`Refs #123`, `PROJ-123`).
- Small obvious changes need only a subject; do not pad.
- Only state things true of the diff. Do not claim tests pass unless you ran them.

Good:

```
fix duplicate invoice on retried webhook

The payment provider resends the webhook when we respond slowly.
Each delivery created a new invoice. Deduplicate on the event id
before creating, and return 200 for already-processed events.
```

Bad: "update stuff", "fix bug", "changes", "WIP", "final fix 2".

## 5. Commit only when asked

Present the message to the user. Run the commit only when they asked you to commit, using a message file or multiple `-m` flags so the body formatting is kept:

```bash
git commit -m "fix duplicate invoice on retried webhook" -m "Body paragraph here."
```

Report the resulting hash and subject (`git log -1 --oneline`).

## Pitfalls

- Do not use `git commit -a` or `git add .` unless the user asked; they may have unrelated changes or untracked secrets.
- Never commit `.env` files, keys or credentials; if the diff contains one, stop and warn.
- Do not skip hooks (`--no-verify`) to get past a failing hook; fix the cause or ask.
- Do not amend or rewrite a previous commit unless the user explicitly asks.
- Do not add trailers or attribution lines that the user or repo does not want; follow their rules.
- Do not describe changes that are not in the diff.

Source: [AnyModel skills catalog](https://anymodel.org/en/skills) · License: [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
