Conventional Commits

When to Use

• Making any git commit -- this skill defines the required format
• Creating PR/MR titles -- squash merges use the title as the commit message
• Writing squash merge messages -- must follow the same format
• Reviewing commit message format -- validate against these rules

Critical Rules

1. Project rules override this skill -- if the project defines commit message conventions (issue number prefixes, custom formats, etc.), follow those instead. This skill is the default when no project-specific rules exist.
2. Type is required -- never commit without a type prefix
3. Description is lowercase, imperative mood, no period:

   fix: handle null response

   not

   Fix: Handled null response.

4. No

   Co-Authored-By

   trailer -- never add it to commit messages
5. Describe the change, not the process -- never write review provenance (

   fix: coderabbit round 2 fixes

   ,

   fix: address review feedback

   ) as the message; state what the commit changes. The trigger for the change already lives in the PR and its threads.
6. No filler -- the description alone is usually the whole message; add a body only for information the description and diff cannot carry (breaking change details, migration steps, non-obvious constraints). Never narrate the diff.

Provider Detection

git remote get-url origin

github.com

gh

gitlab.com

glab

Format

<type>(<optional scope>): <description>

[optional body]

[optional footer(s)]

Types

feat

fix

docs

style

refactor

perf

test

build

ci

chore

Rules

1. Type is required -- never commit without a type prefix
2. Scope is optional but encouraged for multi-module repos:

   feat(auth): add OAuth2 flow

3. Description is lowercase, imperative mood, no period:

   fix: handle null response

   not

   Fix: Handled null response.

4. Breaking changes use

   !

   after type/scope:

   feat(api)!: remove v1 endpoints

5. PR/MR titles follow the same format -- squash merges use the PR/MR title as the commit message
6. No

   Co-Authored-By

   trailer -- never add it to commit messages
7. Describe the change, not the process -- state what changed, never why a reviewer asked for it (see Review-Fix Commits below)
8. Body is optional and rare -- add one only for what the description and diff cannot carry; never restate the diff or pad with narrative

Commit Examples

git commit -m "feat: add user profile page"
git commit -m "fix(auth): prevent token refresh race condition"
git commit -m "docs: update API reference for v2 endpoints"
git commit -m "refactor(db): extract connection pooling logic"
git commit -m "feat(api)!: change response format for /users"

Review-Fix Commits

git log

fix: coderabbit round 2 fixes

fix: guard nil user in session refresh

fix: address PR review feedback

fix: close file handle on early return

chore: apply copilot suggestions

refactor: dedupe retry logic across fetchers

PR/MR Title Examples

gh pr create --title "feat: add dark mode" --body "..."

glab mr create --title "feat: add dark mode" --description "..."