Write Conventional Commits

---
name: "conventional-commits"
description: "Create, review, and improve Git commit messages using Conventional Commits, including scopes, breaking changes, issue references, and release-friendly wording."
---

# Write Conventional Commits

Use this skill to propose a commit message from a diff, review an existing message, or split unrelated changes into release-friendly commits.

## Format

```text
<type>[optional scope][!]: <description>

[optional body]

[optional footer(s)]
```

Use a lowercase type, an optional concise scope, and an imperative description without a trailing period.

## Common types

- `feat`: add user-visible behavior or capability.
- `fix`: correct a defect.
- `docs`: change documentation only.
- `refactor`: restructure code without changing intended behavior.
- `test`: add or correct tests.
- `perf`: improve performance.
- `build`: change dependencies or build tooling.
- `ci`: change automation pipelines.
- `chore`: perform maintenance not covered above.

Follow repository-specific types when a local convention exists.

## Workflow

1. Inspect the actual diff and relevant tests; do not infer the message only from filenames.
2. Identify the single user- or developer-facing purpose of the change.
3. Select the narrowest accurate type and add a scope only when it helps locate the change.
4. Keep the subject specific: say what changed, not that something was “updated”.
5. Add a body when motivation, tradeoffs, migration steps, or non-obvious behavior matter.
6. Mark breaking changes with `!` and a `BREAKING CHANGE:` footer that states the migration impact.
7. Add issue references in footers when identifiers are available.
8. If the diff contains multiple unrelated purposes, recommend separate commits instead of writing a vague umbrella message.

## Examples

```text
feat(auth): refresh expired access tokens
fix(profile): preserve avatar after form validation
docs(api): document pagination parameters
refactor(cart)!: replace numeric item ids with UUIDs
```

## Review checklist

- Does the type match the behavioral impact?
- Is the subject imperative, concise, and concrete?
- Does the scope describe a stable area rather than a temporary filename?
- Is a breaking change explicitly documented?
- Can release tooling and a human reviewer understand the message without opening the diff?

Return one recommended message first. Add alternatives only when the diff genuinely supports more than one interpretation.