Advanced Conventional Commits Skill

Create conventional commits directly for advanced scenarios.

Before Starting

Check the repository state:

git status
git diff --staged
git log --oneline -5

Stop if repository is in conflict state or no changes are staged.

Analyze the Changes

Look at what's staged and determine:

Type - What kind of change is this?

• •feat - new feature
• •fix - bug fix
• •docs - documentation only
• •style - formatting only
• •refactor - code restructure (no behavior change)
• •perf - performance improvement
• •test - test changes
• •build - build/dependency changes
• •ci - CI/CD changes
• •chore - maintenance/tooling

Scope - What part of the project is affected?

• •Look at recent commits to see what scopes are used
• •Use project conventions (like auth, api, ui, db)
• •Use singular form (user not users)

Breaking changes? - Does this break existing functionality?

• •Removed or renamed APIs
• •Changed function signatures
• •Changed response formats
• •Removed configuration options
• •Changed default behaviors

If yes: Use ! marker and include BREAKING CHANGE: footer

Issue references? - Is this linked to any issues?

• •Fixes #123 - for bug fixes
• •Closes #456 - for any issue type
• •Relates to #789 - for references without closing

Write the Commit Message

Header (always)

type(scope): short description

Examples:

• •feat(auth): add two-factor authentication
• •fix(payment): prevent duplicate charges
• •docs(readme): add installation guide

Rules for header:

• •Type lowercase
• •Scope lowercase
• •Description starts lowercase
• •Use imperative mood ("add" not "added")
• •No period at end
• •Keep under 50 characters

Body (if needed)

Add a body when:

• •Change is complex and needs explanation
• •Multiple related changes
• •Breaking change needs migration info

Format:

• •Blank line after header
• •Explain WHY the change was made
• •Keep lines under 72 characters
• •Use bullet points for lists

Example:

feat(auth): add JWT token support

Implement JWT tokens for stateless authentication across the API.

- Add JWT generation and validation service
- Update authentication middleware
- Add refresh token endpoint
- Add token expiration handling

Footer (if needed)

Add footer for breaking changes or issue references.

Breaking change example:

feat(api)!: restructure response format

BREAKING CHANGE: User endpoints now return nested structure

Before:
{ "id": 1, "name": "John" }

After:
{ "user": { "id": 1, "name": "John" } }

Migration: Update clients to access response.user

Closes #567

Issue reference example:

fix(payment): prevent duplicate charges

Users could be charged twice when clicking submit multiple times.

- Add idempotency keys to payment requests
- Disable button during processing
- Add concurrency tests

Fixes #834

Execute the Commit

Build the complete message and use heredoc format:

git commit -m "$(cat <<'EOF'
type(scope): description

Body explaining the change if needed.

BREAKING CHANGE: or issue references if needed
Fixes #123
EOF
)"

Important: Use single quotes in <<'EOF' to prevent shell expansion.

Verify Success

After committing, verify:

git log -1 --format=fuller

Check that:

• •Message is correct
• •No Claude Code signatures present
• •Author is correct
• •All changes included

Critical Rules

Always do:

• •Use imperative mood (add, fix, remove)
• •Keep header under 50 characters
• •Use heredoc for multi-line messages
• •Mark breaking changes with ! and BREAKING CHANGE footer
• •Verify after committing

Never do:

• •Add Claude Code signatures
• •Add "Generated with Claude Code" references
• •Add "Co-Authored-By: Claude" lines
• •Add tool attribution
• •Use past tense in description
• •Capitalize description (unless proper noun)

Multiple Changes

If changes contain multiple unrelated things:

• •Create separate commits for each logical change
• •One commit = one logical unit

Example:

# Commit 1
feat(api): add user endpoint

# Commit 2
chore(deps): upgrade TypeScript

# Commit 3
docs: update API documentation

See Also

Detailed examples and patterns: EXAMPLE.md