commit-helper

Helps write Git commit messages following the Conventional Commits specification. Use this skill when the user asks to commit changes, write commit messages,…

INSTALLATION

npx skills add https://github.com/charon-fan/agent-playbook --skill commit-helper

Run in your project or agent environment. Adjust flags if your CLI version differs.

SKILL.md

Commit Message Helper

Name: commit-helper
Author: charon-fan

A skill for creating properly formatted Git commit messages following the Conventional Commits specification.

When This Skill Activates

This skill activates when you:

Ask to commit changes

Mention commit messages

Request git commit formatting

Say "commit" or "git commit"

Commit Message Format

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

<body>

Types

Type

Description

feat

A new feature

fix

A bug fix

docs

Documentation only changes

style

Changes that do not affect the meaning of the code (formatting, etc.)

refactor

A code change that neither fixes a bug nor adds a feature

perf

A code change that improves performance

test

Adding missing tests or correcting existing tests

chore

Changes to the build process or auxiliary tools

ci

Changes to CI configuration files and scripts

build

Changes that affect the build system or external dependencies

Scope

The scope should indicate the area of the codebase affected:

For frontend: components, hooks, store, styles, utils

For backend: api, models, services, database, auth

For devops: ci, deploy, docker

Project-specific scopes are also acceptable

Guidelines

Subject Line

Use imperative mood ("add feature" not "added feature" or "adds feature")

No period at the end

Maximum 50 characters

Be specific and concise

Body

Separate subject from body with a blank line

Use the body to explain what and why, not how

Wrap at 72 characters per line

Mention any breaking changes

Footer

Reference issues: Closes #123, Fixes #456, Refs #789

Multiple issues: Closes #123, #456, #789

Breaking changes: Start with BREAKING CHANGE: followed by description

Examples

Good Examples

feat(auth): add OAuth2 login support

Implement OAuth2 authentication flow to allow users to log in

with their Google or GitHub accounts.

This change adds:

- New OAuth2 middleware for handling callbacks

- Updated login UI with social login buttons

- User profile synchronization

Closes #123

fix(api): resolve race condition in user creation

The concurrent user creation requests could result in duplicate

email entries. Added unique constraint and proper error handling.

Fixes #456

refactor(user): simplify profile update logic

Extracted common validation logic into a reusable function

to reduce code duplication across profile update endpoints.

docs: update API documentation with new endpoints

Added documentation for the v2 user management endpoints

including request/response examples and error codes.

Bad Examples

updated stuff                    # Too vague, no type/scope

fixed bug                        # No context about which bug

feat: added feature              # Redundant ("feat" means new feature)

Feat(User): Add Login            # Incorrect capitalization

feat: A really really really long subject line that exceeds the recommended limit  # Too long

Breaking Changes

When introducing breaking changes, add BREAKING CHANGE: to the footer:

feat(api): migrate to REST v2

The API endpoints have been restructured for better consistency.

Old endpoints are deprecated and will be removed in v3.0.

BREAKING CHANGE: `/api/v1/users` is now `/api/v2/users`.

All consumers must update their integration by 2025-03-01.

Workflow

When writing a commit message:

Review changes - Run git diff to understand what changed

Identify type - Determine the type of change

Identify scope - Determine which area is affected

Write subject - Create a clear, concise subject line

Write body - Explain what and why (if needed)

Add footer - Reference issues or note breaking changes

Validation

Use the validation script to check commit message format:

python scripts/validate_commit.py "your commit message"

Reference Documents

See references/conventional-commits.md for full specification

See references/examples.md for more examples

See references/scopes.md for recommended scope naming