| name | formatting-commit-messages |
| description | Formats Git commit messages following Conventional Commits conventions. Use when the user asks to commit, write a commit message, format commits, or mentions conventional commits, staged changes, or release notes. |
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
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: buttonsrc/api/users.ts → scope: api or userslib/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 #456Reviewed-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:
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
