What is the Conventional Commits format?

A commit message format of [optional scope][!]: with optional body and footer(s).

How do I indicate breaking changes?

Add a '!' after the type/scope or include a BREAKING CHANGE: footer in the body.

Should I include a body and footers?

Yes, include a body explaining what and why (not how) and optional footers like BREAKING CHANGE or closes references. Wrap lines at 72 chars.

formatting-commit-messages

npx machina-cli add skill WesleySmits/agent-skills/commit-message-formatter --openclaw

Files (1)

SKILL.md

5.6 KB

Commit Message Formatter (Conventional Commits)

When to use this skill

User asks to commit staged changes
User wants help writing a commit message
User mentions "conventional commits" or commit formatting
User asks for release-ready or changelog-friendly commits
User wants to ensure commits follow team standards

Workflow

Check for staged changes using git diff --cached
Analyze the nature of the changes (new feature, bug fix, refactor, etc.)
Determine appropriate type prefix
Identify scope from affected files/modules
Check for breaking changes
Generate formatted commit message
Present message for user approval
Execute commit if approved

Conventional Commits Format

<type>[optional scope][!]: <description>

[optional body]

[optional footer(s)]

Type Prefixes

Type	When to Use
`feat`	New feature for the user
`fix`	Bug fix for the user
`docs`	Documentation only changes
`style`	Formatting, missing semicolons (no code change)
`refactor`	Code change that neither fixes nor adds feature
`perf`	Performance improvement
`test`	Adding or correcting tests
`build`	Changes to build system or dependencies
`ci`	CI configuration changes
`chore`	Other changes that don't modify src or tests
`revert`	Reverts a previous commit

Breaking Changes

Add ! after type/scope: feat(api)!: remove deprecated endpoints
OR add BREAKING CHANGE: footer in the body

Instructions

Step 1: Analyze Staged Changes

Run the following to get staged diffs:

git diff --cached --stat
git diff --cached

Step 2: Determine Commit Type

Analyze the changes to determine the appropriate type:

New files in src/ with new functionality → feat
Modified files fixing incorrect behavior → fix
Changes only to *.md, *.txt, or docs folder → docs
Only whitespace/formatting changes → style
Code restructuring without behavior change → refactor
Performance optimizations → perf
New or updated test files → test
Changes to package.json, webpack.config.*, tsconfig.* → build
Changes to .github/workflows/, CI configs → ci
Dependency updates, config tweaks → chore

Step 3: Identify Scope

Derive scope from the primary affected area:

src/components/Button.tsx → scope: button
src/api/users.ts → scope: api or users
lib/utils/ → scope: utils
Multiple unrelated areas → omit scope

Step 4: Detect Breaking Changes

Look for indicators of breaking changes:

Removed public functions or exports
Changed function signatures (parameters, return types)
Renamed public APIs
Changed default behavior
Removed configuration options

Step 5: Compose the Message

Subject line rules:

Use imperative mood: "add" not "added" or "adds"
No capital letter at start
No period at the end
Max 50 characters (hard limit: 72)

Body (if needed):

Wrap at 72 characters
Explain what and why, not how
Separate from subject with blank line

Footer (if needed):

BREAKING CHANGE: <description>
Fixes #123 or Closes #456
Reviewed-by: Name <email>

Step 6: Present and Commit

Present the formatted message to the user:

**Suggested commit message:**

feat(auth): add OAuth2 login support

Implement OAuth2 authentication flow with Google and GitHub providers.
Users can now sign in using their existing accounts.

Closes #142

If approved, execute:

git commit -m "<subject>" -m "<body>" -m "<footer>"

Or for simple commits:

git commit -m "<type>(<scope>): <description>"

Examples

Simple Feature

feat(cart): add quantity selector to cart items

Bug Fix with Issue Reference

fix(auth): prevent token refresh race condition

Multiple simultaneous requests could trigger parallel refresh attempts.
Added mutex lock to ensure single refresh execution.

Fixes #287

Breaking Change

feat(api)!: migrate to v2 response format

BREAKING CHANGE: API responses now use camelCase keys instead of snake_case.
All clients must update their parsing logic.

Documentation Update

docs(readme): add installation instructions for Windows

Refactor

refactor(utils): extract date formatting into separate module

Validation

Before committing, verify:

Type accurately reflects the change
Scope is specific but not overly narrow
Subject is in imperative mood
Subject is under 50 characters
Breaking changes are properly marked
Related issues are referenced

Error Handling

No staged changes: Run git status to confirm. Prompt user to stage files first.
Commit fails: Check git status for conflicts or hooks blocking commit.
Unsure about a command: Run git commit --help for options.

Resources

Source

git clone https://github.com/WesleySmits/agent-skills/blob/main/.agent/skills/commit-message-formatter/SKILL.mdView on GitHub

Overview

Formats Git commit messages to follow the Conventional Commits standard. It helps analyze staged changes, pick a type and optional scope, and craft a release-friendly message with an optional body and footer.

How This Skill Works

Workflow analyzes staged diffs, determines a type prefix (feat, fix, docs, etc.), derives a scope from affected files, and checks for breaking changes. It then composes the formatted message and presents it for user approval before committing.

When to Use It

User asks to commit staged changes
User wants help writing a commit message
User mentions "conventional commits" or commit formatting
User asks for release-ready or changelog-friendly commits
User wants to ensure commits follow team standards

Quick Start

Step 1: Analyze Staged Changes with git diff --cached --stat and git diff --cached
Step 2: Determine Commit Type and Scope from the changes
Step 3: Present the formatted message for approval and commit if approved

Best Practices

Keep subject under 50 characters and use imperative mood
Use the correct type prefix from the Conventional Commits list (feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert)
Derive scope from the primary affected area when possible
Indicate breaking changes with a trailing '!' or a BREAKING CHANGE footer
Include an optional body and footer explaining what/why, not how; wrap at 72 characters

Example Use Cases

feat(auth): add OAuth2 login support
fix(payment): correct rounding error in total
docs(readme): update installation instructions
style(ui): fix trailing whitespace
perf(api): optimize request caching

Frequently Asked Questions

Add this skill to your agents