Conventional Commits

Overview

The commit skill summarizes the Conventional Commits 1.0.0 specification and common best practices, supporting compliant commit messages. Reference: Conventional Commits 1.0.0.

Commit Format

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

[optional body]

[optional footer(s)]

Elements:

• type (required): Primary intent of the change. feat and fix map to

semantic versioning. Additional allowed types include: docs, style, refactor, perf, test, build, ci, chore, revert.

• scope (optional): Short component or package name in parentheses, e.g.,

feat(parser): ....

• ! (optional): Indicates a breaking change and can appear after type or

scope.

• description (required): Short, imperative summary in lower case (no

trailing period). Aim for ≤ 72 characters.

• body (optional): Explain what/why; wrap at ~72 characters.
• footers (optional): Git trailer format, e.g., BREAKING CHANGE: ...,

Refs: #123, Closes: #123.

Workflow

1. Review changes and identify the primary intent (feature, fix, docs, etc.).
2. Choose the type and optional scope. If changes span multiple intents,

prefer separate commits; otherwise pick the highest-impact type.

1. Determine whether the change is breaking. If yes, add ! and/or a

BREAKING CHANGE: footer.

1. Write a concise description in imperative mood.
2. Add body and footers as needed for context, rationale, or issue links.
3. Validate against the checklist below.

Checklist

• Header matches <type>(<scope>): <description> format.
• Type is correct for the change (feat/fix for user-facing behavior).
• Description is imperative, ≤ 72 chars, and has no trailing period.
• Breaking changes are marked with ! and/or BREAKING CHANGE:.
• Footers follow Token: value format.

Examples

• feat(auth): add refresh token rotation
• fix(api): handle empty payloads
• docs: add migration guide
• refactor(ui): extract button variants
• perf(db): batch writes to reduce roundtrips
• chore(deps): bump eslint to 9.0.0

Breaking change:

feat(api)!: drop deprecated v1 endpoints

BREAKING CHANGE: v1 endpoints were removed. Use /v2 instead.

Revert:

revert: feat(auth): add refresh token rotation

This reverts commit 1234abcd.

Tips

• Use scopes for packages or subsystems (e.g., api, ui, cli).
• Avoid mixing unrelated changes in a single commit.
• Use style or chore for formatting-only changes.
• Use ci or build for pipeline and dependency changes.
• Use test for changes limited to tests.