conventional-commits | agent-skills-collection

Stats

Actions

Tags

conventional-commits | agent-skills-collection

Conventional Commits

Overview

Conventional Commits is a specification for adding human and machine-readable meaning to commit messages. It provides a standardized format that enables automated tools to generate changelogs, determine semantic version bumps, and communicate the nature of changes clearly.

When to Use

Use this skill when:

Creating git commits for any codebase
Writing commit messages that need to follow a standard format
The user mentions conventional commits, semantic versioning, or automated changelogs
Working on projects that use automated release pipelines
Contributing to open-source projects that require conventional commit format

Commit Message Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Required Elements

Type: A noun indicating the category of change
Description: A short summary of the change

Optional Elements

Scope: Context for the change (in parentheses)
Body: Detailed explanation (separated by blank line)
Footer(s): Metadata like breaking changes or issue references

Commit Types

Core Types (Semantic Versioning Impact)

Type	Meaning	Version Bump
`feat`	New feature	MINOR
`fix`	Bug fix	PATCH
`feat!` or `feat` with `BREAKING CHANGE` footer	Breaking change	MAJOR

Additional Types (No Version Impact)

Type	Meaning
`build`	Build system or external dependencies
`chore`	Maintenance tasks, no production code changes
`ci`	CI/CD configuration and scripts
`docs`	Documentation only changes
`style`	Code style (formatting, semicolons, etc.)
`refactor`	Code refactoring without fixing bugs or adding features
`perf`	Performance improvements
`test`	Adding or modifying tests
`revert`	Reverting a previous commit

Examples

Simple Commit

docs: update README with installation instructions

Commit with Scope

feat(api): add user authentication endpoint

Commit with Body

fix: prevent race condition in request handler

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Breaking Change (Footer Style)

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Breaking Change (Shorthand Style)

feat!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.

Multiple Footers

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Reviewed-by: Z
Refs: #123

Writing Good Descriptions

Do's

Use imperative mood ("add" not "added" or "adds")
Start with lowercase letter
No period at the end
Be concise but descriptive
Explain WHAT and WHY, not HOW

Don'ts

Don't use vague descriptions like "fix bug" or "update code"
Don't include issue numbers in the description (use footer instead)
Don't write long descriptions (use body instead)

Common Patterns

Feature Addition

feat(auth): implement OAuth2 login flow

Add support for OAuth2 authentication with Google and GitHub providers.
Includes token refresh logic and session management.

Closes #234

Bug Fix

fix(parser): handle empty input gracefully

Parser was throwing NullPointerException when receiving empty string.
Added null check and return empty result set instead.

Fixes #567

Breaking Change

refactor(api)!: rename user endpoints

BREAKING CHANGE: All /user/* endpoints renamed to /users/*
- /user/profile -> /users/profile
- /user/settings -> /users/settings

Migration guide: Update API client base paths

Documentation

docs(contributing): add PR submission guidelines

Add step-by-step guide for submitting pull requests including:
- Branch naming conventions
- Commit message format
- Required CI checks

Workflow Integration

Pre-commit Hooks

Use tools like commitlint to enforce conventional commit format:

{
  "extends": ["@commitlint/config-conventional"],
  "rules": {
    "type-enum": [
      2,
      "always",
      [
        "feat",
        "fix",
        "docs",
        "style",
        "refactor",
        "perf",
        "test",
        "build",
        "ci",
        "chore",
        "revert"
      ]
    ]
  }
}

Automated Changelog Generation

Tools like standard-version or semantic-release can automatically:

Generate CHANGELOG.md from commit messages
Bump version numbers based on commit types
Create git tags and GitHub releases

CI/CD Integration

# Example GitHub Actions workflow
- name: Semantic Release
  uses: cycjimmy/semantic-release-action@v3
  with:
    semantic_version: 18
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Best Practices

One concern per commit: Each commit should address one issue or feature
Atomic commits: Commits should be self-contained and reversible
Write commits first: Draft commit messages before writing code
Use scopes wisely: Scopes should be consistent across the project
Reference issues: Use footers to link to issues, PRs, or tickets
Test before committing: Ensure tests pass before creating commits
Review your own diff: Always review changes before committing

Common Mistakes

Mistake	Correction
`feat: Added new feature`	`feat: add new feature` (imperative mood)
`feat: Add new feature.`	`feat: add new feature` (no period)
`feat: Add New Feature`	`feat: add new feature` (lowercase)
`feat(api,auth): ...`	`feat(api): ...` (one scope)
`feat: fix bug`	`fix: fix bug` (correct type)
`feat: add feature (#123)`	Use footer: `Refs: #123`

Specification Compliance

This skill follows the Conventional Commits specification v1.0.0. For the complete specification, see: https://www.conventionalcommits.org/

Key rules from the specification:

Commits MUST be prefixed with a type
Type MUST be followed by a colon and space
Scope is OPTIONAL and enclosed in parentheses
Breaking changes MUST be indicated with ! or BREAKING CHANGE footer
Types other than feat and fix are allowed
The specification is case-insensitive except for BREAKING CHANGE

Quick Reference

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

Breaking: Add ! after type/scope OR add BREAKING CHANGE: footer

Version Impact: feat → MINOR, fix → PATCH, BREAKING CHANGE → MAJOR