Conventional Commits Skill

What I do

• •Provide comprehensive guidance on the Conventional Commits v1.0.0 specification
• •Help write clear, structured commit messages that enable automation
• •Explain commit types, scopes, and their semantic versioning impact
• •Guide on writing breaking changes and commit message bodies
• •Offer examples of good vs. bad commit messages
• •Support automated changelog generation and version management

When to use me

Use this skill when you need to:

• •Write commit messages following the Conventional Commits specification
• •Understand which commit type to use (feat, fix, refactor, etc.)
• •Communicate breaking changes in commits
• •Enable automated semantic versioning in your project
• •Generate changelogs automatically from commit history
• •Improve team collaboration through structured commit messages
• •Integrate with CI/CD pipelines that rely on conventional commits

How I work

I provide structured guidance through:

1. •Specification Format - Detailed explanation of the commit message structure
2. •Commit Types - Core and additional types with clear use cases
3. •Breaking Changes - How to communicate breaking changes properly
4. •Examples - Real-world examples of good commit messages
5. •Best Practices - DO/DON'T patterns for effective commits
6. •Semantic Versioning - How commits map to version bumps
7. •Anti-patterns - Common mistakes to avoid

Conventional Commits v1.0.0

Overview

Conventional Commits is a specification for adding human and machine-readable meaning to commit messages. This skill provides guidance for writing conventional commits that enable automated versioning, changelog generation, and better team collaboration.

Specification Format

Basic Structure

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Required Elements

• •type: Must be one of the core types
• •description: Short, imperative mood summary of changes
• •colon and space: Required separator (:)

Core Commit Types

Required Types

• •feat: A new feature for the user (correlates with MINOR in SemVer)
• •fix: A bug fix for the user (correlates with PATCH in SemVer)

Common Additional Types

• •build: Changes that affect the build system or external dependencies
• •chore: Routine tasks, dependency updates, maintenance
• •ci: Changes to CI configuration files and scripts
• •docs: Documentation only changes
• •style: Code style changes (formatting, missing semicolons, etc.)
• •refactor: Code refactoring that neither fixes a bug nor adds a feature
• •perf: Performance improvements
• •test: Adding missing tests or correcting existing tests

Breaking Changes

Method 1: Exclamation Mark

feat!: drop support for Node 6
feat(api)!: remove deprecated endpoint

Method 2: BREAKING CHANGE Footer

feat: add new pattern API

BREAKING CHANGE: The 'pattern' key in the configuration object is now required.

Examples

Simple Commits

feat: add user authentication
fix: resolve memory leak in data processing
docs: update API documentation

Commits with Scope

feat(auth): implement OAuth2 login
fix(parser): handle empty input gracefully
test(unit): add coverage for math utilities

Commits with Body

feat: add user profile picture upload

Adds multipart form data handling for profile picture uploads.
Supports JPEG, PNG, and WebP formats up to 5MB.

Commits with Footers

fix: correct validation error messages

Addresses incorrect error text shown when form validation fails.

Closes #123
Reviewed-by: @username

Complex Example

feat(api)!: change authentication from Basic Auth to Bearer Token

Deprecates Basic Auth in favor of JWT Bearer tokens for improved security.
Migration guide available in docs/authentication.md.

BREAKING CHANGE: All API requests now require Authorization: Bearer <token>
header instead of Basic Auth credentials.

Closes #456
Co-authored-by: @teammate

Best Practices

Description Guidelines

• •Use imperative mood ("add feature" not "added feature" or "adds feature")
• •Keep it short and simple under 50 characters when possible
• •Describe what changed, not why
• •Use lowercase except for proper nouns

Scope Guidelines

• •Use scope to indicate the module/package affected
• •Keep scope names short and consistent
• •Common examples: auth, api, ui, parser, database

Body Guidelines

• •Use the body to explain what and why, not how
• •Include migration instructions for breaking changes
• •Reference related issues with footers

Footer Guidelines

• •Use footers for metadata like issue references
• •Common footers: Closes #123, Reviewed-by: @user, Co-authored-by: @user
• •Use BREAKING CHANGE: for major changes not indicated with !

Integration with SemVer

Automatic Versioning

• •fix commits → PATCH version (1.0.0 → 1.0.1)
• •feat commits → MINOR version (1.0.0 → 1.1.0)
• •BREAKING CHANGE → MAJOR version (1.0.0 → 2.0.0)

Tools That Use This Specification

• •semantic-release: Automated version publishing
• •standard-version: Changelog generation
• •conventional-changelog: Various changelog generators
• •Commitizen: Interactive commit message helper

Common Anti-Patterns to Avoid

Don't Do This

feat: added new feature  # Wrong tense
fix: fix the bug         # Redundant
feat: feature            # Too vague
feat(users): lots of stuff # Not descriptive

Do This Instead

feat: add user profile feature
fix: resolve authentication timeout
feat: implement user profile management
feat(users): add profile editing capabilities

Git Hooks and Validation

Pre-commit Hooks

Consider using tools like:

• •commitlint: Lints commit messages against conventions
• •husky: Git hooks made easy
• •commitizen: Standardized commit messages

Example commitlint.config.js

module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [2, 'always', [
      'feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore'
    ]],
    'subject-max-length': [2, 'always', 50],
    'body-max-line-length': [2, 'always', 72]
  }
};

Migration Tips

For teams adopting conventional commits:

1. •Start gradually - apply to new commits first
2. •Use commitlint - enforce automatically
3. •Provide templates - help team members learn format
4. •Review in PRs - catch issues before merge
5. •Generate changelog - show immediate benefits

Quick Reference

<type>[!](<scope>): <subject>

<body>

<footer(s)>

Types: feat, fix, docs, style, refactor, test, chore, build, ci, perf Breaking: feat!: change OR BREAKING CHANGE: description Footer: Closes #123, Reviewed-by: @user, Co-authored-by: @user