| name | commit-message-writer |
| description | Writes a well-formed git commit message. Use when the user says write a commit, commit message, what should my commit say, help me commit, or draft a commit. Apply even when the user just says 'commit this' or shares a diff without explicitly asking for a message. |
| typicalNext | Run `tone-check` if you want a second pass on the wording before committing. |
Commit Message Writer
When to Use
Invoke when the user wants to write or improve a git commit message, given a diff, a list of changed files, or a plain-language description of what changed.
Project contract
The commit-message format, issue-ref convention, and any required commit annotations are
project-specific. Read them from .agents/project-contract.md (shared contract), then layer .agents/project-contract.personal.md on top if it exists (personal entries win where they overlap):
## Commit conventions: the message format, the required-fields regex (if any), and any
per-commit annotations this project mandates (e.g. an embedded issue ref, a Release Notes line).## Tracker → Issue ref format: how this project writes an issue reference (e.g. PROJ-123
for Jira, #NNNN for GitHub). Use this whenever the convention embeds a ref in the message.## Voice: the voice config to apply to the subject and body.## Attribution marker: only if the project contract defines one (see Attribution below).
If no project contract is present, fall back to the generic methodology below: conventional-commit-style
subject, imperative mood, one sentence, no required ref. Ask the user for the project's commit
convention rather than inventing a ref format.
Approach
- Gather context, diff, changed files, issue/ticket reference, or description of the change
- Identify the change type: fix / feat / refactor / chore / test / docs / style
- Write the message per the project contract's
## Commit conventions:
- Imperative mood ("Add", "Fix", "Remove", not "Added", "Fixed")
- Apply the project contract's message Format (e.g. an embedded issue ref in the project contract's
## Tracker → Issue ref format, or a conventional-commit prefix)
- 1 sentence, 2 at most, no body block (unless the convention requires one, e.g. a
Release Notes statement)
- 10 characters minimum of meaningful subject, 72 characters max
- Match any required-fields regex the project contract defines
- Check tone, use
tone-check skill on the drafted message before finalizing
- Flag if scope is too broad, suggest splitting into multiple commits
Output Format
Output the message in the project contract's commit format, e.g.:
[issue-ref or prefix]: Brief imperative description of the change.
Provide 1–3 alternatives if the change could be framed multiple ways.
General conventions
These hold regardless of project:
- Use imperative mood in the subject line
- Keep it to 1 sentence, 2 at most, with no body block unless the convention requires one
- Never include "WIP" in a commit intended for merge
- Separate unrelated changes into separate commits
Example
You ask: use the commit-message-writer skill on this diff
You get:
PROJ-1234: Clear overflow lock after facet deselect.
Alternatives:
PROJ-1234: Remove stale overflow:hidden after ajaxComplete.
PROJ-1234: Fix page scroll lock on filter deselect.
Related Skills
- Invokes:
tone-check (validates tone before finalizing any message)
- Invoked by:
organize-commits (writes a message for each proposed commit), squash-commits (writes the squashed message)
Voice
Apply the voice config from the project contract's ## Voice section (e.g. .agents/style/voice.md). Apply
it to the subject line, body, and any alternatives generated.
Attribution
A commit message is not a shared artifact in the same way a ticket or PR description is, so this
skill does not emit a marker by default. If the active project contract's ## Attribution marker section
calls for marking AI-assisted commit messages, honor it; otherwise emit none.
