---

name: conventional-commits description: Write conventional commits following v1.0.0 specification for semantic versioning and automated changelogs license: MIT compatibility: opencode metadata: audience: developers workflow: git version: 1.0.0

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

Copy<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

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

Method 2: BREAKING CHANGE Footer

Copyfeat: add new pattern API

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

Examples

Simple Commits

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

Commits with Scope

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

Commits with Body

Copyfeat: 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

Copyfix: correct validation error messages

Addresses incorrect error text shown when form validation fails.

Closes #123
Reviewed-by: @username

Complex Example

Copyfeat(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

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

Do This Instead

Copyfeat: 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

Copymodule.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

Copy<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