name	conventional-commits
description	Generate conventional commit messages following the project's commitlint rules with proper scopes. Use when committing changes to ensure semantic versioning works correctly.
allowed-tools	Bash, Read

Conventional Commits Skill

This skill helps you create proper conventional commit messages for semantic versioning.

When to Use This Skill

Creating git commits
Ensuring semantic release works correctly
Understanding commit message format
Fixing commit message errors
Planning version bumps
Writing meaningful commit messages

Conventional Commits Format

<type>(<scope>): <subject>

<body>

<footer>

Required Elements

type: Category of change (feat, fix, chore, etc.)
subject: Brief description (imperative mood, lowercase, no period)

Optional Elements

scope: Package or area affected (api, web, database, etc.)
body: Detailed description
footer: Breaking changes, issue references

Commit Types

Version Bumping Types

feat - New feature (minor version bump)

git commit -m "feat: add user authentication"
git commit -m "feat(api): add COE data endpoint"

fix - Bug fix (patch version bump)

git commit -m "fix: resolve database connection timeout"
git commit -m "fix(web): fix chart rendering issue"

feat! or BREAKING CHANGE - Breaking change (major version bump)

git commit -m "feat!: change API response format"
git commit -m "fix!: remove deprecated endpoints"

# Or with footer
git commit -m "feat: redesign auth system

BREAKING CHANGE: Auth tokens now use JWT format"

Non-Version Bumping Types

chore - Maintenance tasks, no production code change

git commit -m "chore: update dependencies"
git commit -m "chore(deps): upgrade Next.js to v16"

docs - Documentation only

git commit -m "docs: update README with deployment steps"
git commit -m "docs(api): add API documentation"

refactor - Code refactoring, no functional changes

git commit -m "refactor: simplify cache logic"
git commit -m "refactor(database): optimize query performance"

test - Adding or updating tests

git commit -m "test: add unit tests for auth service"
git commit -m "test(web): add E2E tests for checkout flow"

style - Code style changes (formatting, whitespace)

git commit -m "style: format code with Biome"
git commit -m "style: fix linting errors"

perf - Performance improvements

git commit -m "perf: optimize database queries"
git commit -m "perf(web): reduce bundle size"

ci - CI/CD changes

git commit -m "ci: add deployment workflow"
git commit -m "ci: fix GitHub Actions syntax"

build - Build system changes

git commit -m "build: update Turbo configuration"
git commit -m "build: add new package to monorepo"

revert - Revert previous commit

git commit -m "revert: revert 'feat: add feature X'"

Available Scopes

Project-specific scopes:

api: API service (apps/api)
web: Web application (apps/web)
admin: Admin application (apps/admin)
docs: Documentation (apps/docs)
database: Database package (packages/database)
types: Types package (packages/types)
ui: UI package (packages/ui)
utils: Utils package (packages/utils)
logos: Logos package (packages/logos)
infra: Infrastructure (infra/)
deps: Dependency updates
release: Release-related changes

Commit Message Guidelines

Subject Line

✅ Good:

feat: add user authentication
fix: resolve memory leak in cache
chore: update Next.js to v16

❌ Bad:

feat: Add user authentication.  # No period
Fix: resolve memory leak        # Capitalized
added new feature               # No type

Rules

Imperative mood: Use "add" not "added" or "adds"
Lowercase: Subject should be lowercase
No period: Don't end subject with period
50 chars max: Keep subject concise (72 chars absolute max)
Be specific: Describe what changed, not how

Body

Use body for detailed explanation:

git commit -m "feat: add blog post generation

Implemented LLM-powered blog generation using Google Gemini.
Posts are automatically generated from car registration data
and published to the website.

Features:
- Gemini API integration
- Automated content generation
- Publishing workflow"

Footer

Use footer for breaking changes and issue references:

git commit -m "feat: redesign API authentication

BREAKING CHANGE: Authentication now requires JWT tokens
instead of API keys. Update clients to use new auth flow.

Closes #123
Refs #456"

Examples by Scenario

Adding a Feature

# Simple feature
git commit -m "feat(web): add dark mode toggle"

# Feature with scope
git commit -m "feat(api): add COE bidding data endpoint"

# Feature with body
git commit -m "feat(web): add interactive charts

Implemented interactive charts for car registration data
using Recharts library. Charts support filtering by make,
model, and date range."

Fixing a Bug

# Simple fix
git commit -m "fix(api): resolve database connection timeout"

# Fix with details
git commit -m "fix(web): fix chart rendering on mobile

Charts were not rendering correctly on mobile devices
due to incorrect responsive container configuration.
Updated chart components to use proper breakpoints."

# Critical fix
git commit -m "fix!: resolve security vulnerability in auth

BREAKING CHANGE: Auth tokens now require additional
signature verification. Clients must update to new SDK."

Updating Dependencies

# Single dependency
git commit -m "chore(deps): upgrade Next.js to v16"

# Multiple dependencies
git commit -m "chore(deps): update dependencies

- Next.js 15 → 16
- React 18 → 19
- Drizzle ORM 0.28 → 0.30"

# Security update
git commit -m "fix(deps): update vulnerable packages

Updated packages with known security vulnerabilities:
- axios 0.27.0 → 1.6.0 (CVE-2023-45857)
- express 4.17.1 → 4.18.2"

Refactoring

# Code refactoring
git commit -m "refactor(database): simplify migration logic"

# Extract component
git commit -m "refactor(web): extract reusable Button component"

# Rename
git commit -m "refactor(api): rename getCwd to getCurrentWorkingDirectory"

Documentation

# Update docs
git commit -m "docs: update deployment instructions"

# Add docs
git commit -m "docs(api): add API endpoint documentation"

# Fix typos
git commit -m "docs: fix typos in README"

Tests

# Add tests
git commit -m "test(api): add unit tests for auth service"

# Update tests
git commit -m "test(web): update E2E tests for new flow"

# Fix failing tests
git commit -m "test: fix flaky integration tests"

Chores

# Update config
git commit -m "chore: update TypeScript config"

# Clean up
git commit -m "chore: remove unused dependencies"

# Tooling
git commit -m "chore: add Biome configuration"

Version Bump Examples

Patch (0.0.x)

Bug fixes, no new features:

git commit -m "fix: resolve login error"
git commit -m "fix(web): fix broken link in navigation"

Minor (0.x.0)

New features, backwards compatible:

git commit -m "feat: add export to CSV functionality"
git commit -m "feat(api): add pagination to car data endpoint"

Major (x.0.0)

Breaking changes:

git commit -m "feat!: redesign API response format"
git commit -m "fix!: remove deprecated auth method

BREAKING CHANGE: API keys no longer supported.
Use JWT tokens for authentication."

Multi-Package Commits

When changes affect multiple packages:

# Scoped to main package
git commit -m "feat(web): add new dashboard page

Also updates:
- packages/ui: add new components
- packages/types: add dashboard types"

# No scope if truly cross-cutting
git commit -m "chore: update TypeScript to v5

Updates TypeScript across all packages to v5.0"

Breaking Changes

Explicit Breaking Change

git commit -m "feat!: change database schema

BREAKING CHANGE: User table renamed to users.
Run migration before deploying."

With Description

git commit -m "refactor!: redesign authentication

BREAKING CHANGE: Authentication flow completely redesigned.

Migration Guide:
1. Update auth tokens to JWT format
2. Replace getUser() with getCurrentUser()
3. Update middleware to use new auth context

Closes #234"

Issue References

Link commits to issues:

# Closes an issue
git commit -m "fix: resolve login timeout

Closes #123"

# References an issue
git commit -m "feat: add user profile page

Refs #456"

# Multiple issues
git commit -m "fix: resolve multiple auth bugs

Closes #123, #124, #125"

Commit Message Template

Create a commit template:

# ~/.gitmessage
# <type>(<scope>): <subject>
#
# <body>
#
# <footer>
#
# Types: feat, fix, docs, style, refactor, perf, test, chore
# Scopes: api, web, admin, docs, database, types, ui, utils, infra, deps
#
# Remember:
# - Use imperative mood (add, fix, update)
# - Keep subject under 50 characters
# - Separate subject from body with blank line
# - Wrap body at 72 characters
# - Use body to explain what and why, not how
# - Use footer for breaking changes and issue refs

Set as default:

git config --global commit.template ~/.gitmessage

Commitlint Configuration

The project uses commitlint to enforce rules:

// commitlint.config.js
module.exports = {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "type-enum": [
      2,
      "always",
      [
        "feat",
        "fix",
        "docs",
        "style",
        "refactor",
        "perf",
        "test",
        "build",
        "ci",
        "chore",
        "revert",
      ],
    ],
    "scope-enum": [
      2,
      "always",
      [
        "api",
        "web",
        "admin",
        "docs",
        "database",
        "types",
        "ui",
        "utils",
        "logos",
        "infra",
        "deps",
        "release",
      ],
    ],
    "subject-case": [2, "always", "lower-case"],
    "subject-empty": [2, "never"],
    "subject-full-stop": [2, "never", "."],
    "header-max-length": [2, "always", 72],
  },
};

Husky Integration

Commits are validated on commit:

# .husky/commit-msg
npx --no -- commitlint --edit $1

If commit fails:

git commit -m "bad commit"
# ✖ subject may not be empty [subject-empty]
# ✖ type may not be empty [type-empty]

Fix and retry:

git commit -m "feat: add new feature"
# ✔ Commit message passes validation

Amending Commits

Fix commit message:

# Amend last commit message
git commit --amend

# Amend without changing message
git commit --amend --no-edit

Viewing Commit History

# See recent commits
git log --oneline -10

# See commits with type
git log --oneline --grep="^feat"
git log --oneline --grep="^fix"

# See commits for specific scope
git log --oneline --grep="(web)"
git log --oneline --grep="(api)"

Semantic Release

The project uses semantic-release to automatically:

Determine version bump based on commits
Generate changelog
Create git tag
Publish release

Commit types → Version bump:

feat: → Minor (0.x.0)
fix: → Patch (0.0.x)
feat!: or BREAKING CHANGE: → Major (x.0.0)
Other types → No bump

Quick Reference

# New feature
feat: <description>
feat(<scope>): <description>

# Bug fix
fix: <description>
fix(<scope>): <description>

# Breaking change
feat!: <description>
fix!: <description>

# No version bump
chore: <description>
docs: <description>
refactor: <description>
test: <description>
style: <description>

# With body and footer
type(scope): subject

Detailed explanation here

BREAKING CHANGE: Description
Closes #123

Troubleshooting

Commit Rejected

Error: subject may not be empty Fix: Add subject after colon

git commit -m "feat: add user login"

Error: type may not be empty Fix: Add valid type

git commit -m "feat: add feature"

Error: scope must be one of [...] Fix: Use valid scope or omit

git commit -m "feat(api): add endpoint"
# or
git commit -m "feat: add endpoint"

Error: header must not be longer than 72 characters Fix: Shorten subject, use body for details

git commit -m "feat: add feature

Detailed explanation goes in body, not subject line"

References

Conventional Commits: https://www.conventionalcommits.org
Commitlint: https://commitlint.js.org
Semantic Release: https://semantic-release.gitbook.io
Related files:
- commitlint.config.js - Commitlint configuration
- Root CLAUDE.md - Commit message guidelines

Best Practices

Clear Subjects: Write clear, concise subjects
Proper Types: Use correct type for the change
Scopes: Add scope when change is package-specific
Breaking Changes: Mark breaking changes explicitly
Issue Links: Reference issues in footer
Imperative Mood: Use "add" not "added"
Lowercase: Keep subject lowercase
No Period: Don't end subject with period

Install Skill

SKILL.md