Formatting Commit Messages

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

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

• Conventional Commits Specification
• Angular Commit Guidelines