| name | write-conventional-commit |
| description | Create Git commit messages that conform to Conventional Commits 1.0.0, including type/scope/description format, optional body, trailer-style footers, and explicit BREAKING CHANGE signaling. Use when users ask to draft commit messages, commit current changes, rewrite a commit message into conventional format, or enforce conventional commit standards in a repo. |
Write Conventional Commit
Generate and apply Conventional Commits that follow the 1.0.0 specification.
Workflow
Step 1: Inspect commit scope
Run from repository root:
git status --short
git diff --staged --name-only
git diff --name-only
Use staged changes when available. If nothing is staged and the user asked to commit now, stage intentionally relevant files first and state what was staged.
Step 2: Classify intent into commit type
Pick the best type from change intent, not from file extension.
Common types:
feat: add a user-facing featurefix: fix a bugrefactor: code change without new feature or bug fixperf: improve performancedocs: documentation onlytest: add/update testsbuild: build/dependency toolingci: CI/CD configurationchore: maintenance that does not fit aboverevert: revert a previous commit
If uncertain between feat and fix, prefer:
fix when correcting broken behaviorfeat when adding new behavior
Step 3: Choose optional scope
Scope is optional and should be short and stable.
Prefer one of:
- top-level package/app (
api, billing, auth)
- subsystem (
migrations, deps, release)
- user-visible surface (
checkout, search)
Avoid broad scopes like misc.
Step 4: Detect breaking changes
Mark breaking changes when diff indicates incompatible API/contract behavior.
Signals include:
- removed/renamed public endpoints, fields, events, CLI flags
- required inputs changed incompatibly
- output schema changed incompatibly
When breaking:
- Add
! after type or type+scope (feat!: or feat(api)!:)
- Add footer:
BREAKING CHANGE: <what changed and how to migrate>
Use both when possible for clarity.
Step 5: Compose message in spec format
Use this structure exactly:
<type>[optional scope][!]: <description>
[optional body]
[optional footer(s)]
Formatting rules:
- Header type must be lowercase noun.
- Put a colon and single space after header prefix.
- Keep description concise and specific.
- Put one blank line between header and body.
- Put one blank line between body and footers.
- Footer tokens follow git trailer style (
Token: value), except references may use Token #value.
- Use
BREAKING CHANGE: as the canonical breaking footer token.
Step 6: Create commit (when requested)
If user wants the commit executed, run non-interactively:
git commit -m "<header>" -m "<body>" -m "<footer1>" -m "<footer2>"
Only include -m blocks that are needed.
For multiline body/footer with precise formatting, use:
git commit -F /tmp/commit-msg.txt
Then report:
- final commit header
- commit hash
- whether breaking change was marked
Quality checks
Before finalizing, verify:
- Header matches
<type>[scope][!]: description
- Type reflects intent correctly
- Scope is helpful or omitted
- Breaking changes are explicitly marked when applicable
- Body explains why when context is not obvious
- Footers are valid trailers and references are accurate
Output behavior
When user asks only for message suggestions, provide 1 recommended message and up to 2 alternatives.
When user asks to commit directly, proceed with staging/commit commands and then return commit result.
Reference
Read references/conventional-commits-1.0.0.md for the normative checklist and examples.
