MCP HubMCP Hub
← Back to Skills

conventional-commits

sgcarstrends
Updated Today
21 views
9
1
9
View on GitHub
Metageneral

About

This skill generates conventional commit messages that follow your project's commitlint rules with proper scopes. Use it when creating git commits to ensure semantic versioning works correctly and maintain consistent commit message formatting. It helps developers write meaningful commits with the correct type, scope, and structure.

Documentation

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

  1. Imperative mood: Use "add" not "added" or "adds"
  2. Lowercase: Subject should be lowercase
  3. No period: Don't end subject with period
  4. 50 chars max: Keep subject concise (72 chars absolute max)
  5. 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:

  1. Determine version bump based on commits
  2. Generate changelog
  3. Create git tag
  4. 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

Best Practices

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

Quick Install

/plugin add https://github.com/sgcarstrends/sgcarstrends/tree/main/conventional-commits

Copy and paste this command in Claude Code to install this skill

GitHub 仓库

sgcarstrends/sgcarstrends
Path: .claude/skills/conventional-commits
apiaws-lambdabackendhonojob-schedulerneon-postgres

Related Skills

subagent-driven-development

Development

This skill executes implementation plans by dispatching a fresh subagent for each independent task, with code review between tasks. It enables fast iteration while maintaining quality gates through this review process. Use it when working on mostly independent tasks within the same session to ensure continuous progress with built-in quality checks.

View skill

algorithmic-art

Meta

This Claude Skill creates original algorithmic art using p5.js with seeded randomness and interactive parameters. It generates .md files for algorithmic philosophies, plus .html and .js files for interactive generative art implementations. Use it when developers need to create flow fields, particle systems, or other computational art while avoiding copyright issues.

View skill

executing-plans

Design

Use the executing-plans skill when you have a complete implementation plan to execute in controlled batches with review checkpoints. It loads and critically reviews the plan, then executes tasks in small batches (default 3 tasks) while reporting progress between each batch for architect review. This ensures systematic implementation with built-in quality control checkpoints.

View skill

cost-optimization

Other

This Claude Skill helps developers optimize cloud costs through resource rightsizing, tagging strategies, and spending analysis. It provides a framework for reducing cloud expenses and implementing cost governance across AWS, Azure, and GCP. Use it when you need to analyze infrastructure costs, right-size resources, or meet budget constraints.

View skill