Generate conventional commit messages by analyzing staged changes automatically
---
name: git-commit-message-generator
description: Generate conventional commit messages by analyzing staged changes automatically
version: 1.0.0
metadata:
openclaw:
emoji: "π"
homepage: https://www.conventionalcommits.org
requires:
bins:
- git
os: ["macos", "linux", "windows"]
---
# Git Commit Message Generator
Automatically generates high-quality conventional commit messages by analyzing your staged Git changes. No more staring at a blank commit message wondering what to write - this skill reads your `git diff`, understands the context, and creates a properly formatted commit message following the Conventional Commits specification.
## What This Skill Does
This skill analyzes your staged changes and generates commit messages that follow the Conventional Commits format:
```
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
```
It intelligently detects:
- **Change type** (feat, fix, docs, style, refactor, test, chore, perf, ci, build)
- **Affected scope** (component, module, or file area)
- **Breaking changes** (from API signature changes, removed exports, etc.)
- **Related issues** (from branch names or file patterns)
- **Appropriate detail level** (when to add body/footer sections)
## Why Use This Skill
### Saves Time
- No more thinking "what should I write?" for 2-3 minutes per commit
- Eliminates typos and formatting inconsistencies
- Reduces commit message review comments in PRs
### Improves Quality
- Consistent conventional commit format across your team
- Accurate change type detection (feat vs fix vs refactor)
- Proper scope identification (which module/component changed)
- Captures breaking changes automatically
- Follows best practices (imperative mood, 50-char title, 72-char body)
### Enables Automation
- Conventional commits enable automated changelog generation
- Semantic versioning can be automated from commit types
- CI/CD pipelines can trigger based on commit types
- Git history becomes machine-readable
## When to Use This Skill
Use this skill whenever you're about to commit code:
- β
After staging changes with `git add`
- β
When working on feature branches
- β
During bug fixes
- β
For documentation updates
- β
When refactoring code
- β
For dependency updates
- β
During code reviews (helping others improve commits)
## When NOT to Use This Skill
- β For merge commits (use default merge messages)
- β For revert commits (use `git revert` auto-messages)
- β When you have NO staged changes (nothing to analyze)
- β For initial commits (use "chore: initial commit" or "feat: initial implementation")
## How It Works
### Step-by-Step Process
1. **Reads staged changes**: Executes `git diff --staged` to see what you're about to commit
2. **Analyzes file patterns**: Identifies which files changed (components, tests, docs, config)
3. **Detects change type**: Determines if it's a feature, fix, refactor, etc.
4. **Identifies scope**: Extracts the affected module/component name
5. **Checks for breaking changes**: Looks for API changes, removed exports, major refactors
6. **Generates message**: Creates a properly formatted conventional commit message
7. **Validates format**: Ensures it follows best practices (length, mood, structure)
### Detection Logic
**Type Detection:**
- `feat:` - New files in src/, new functions/classes, new exports
- `fix:` - Changes to existing logic, bug-related file names, error handling
- `docs:` - Changes to .md files, JSDoc/comments, README updates
- `test:` - Changes to test files, spec files, test utilities
- `refactor:` - Code restructuring without behavior change, renaming, cleanup
- `style:` - Formatting, linting fixes, whitespace, semicolons
- `perf:` - Performance optimizations, caching, algorithm improvements
- `build:` - package.json, webpack, build scripts, dependencies
- `ci:` - GitHub Actions, .yml files, CI config
- `chore:` - Tooling, configs, gitignore, minor maintenance
**Scope Detection:**
- Extracts component name from file path: `src/components/Button.tsx` β `(button)`
- Uses directory name for modules: `src/auth/login.ts` β `(auth)`
- Detects common scopes: `(api)`, `(ui)`, `(db)`, `(tests)`, `(docs)`
- Falls back to primary changed directory if ambiguous
**Breaking Change Detection:**
- Function signature changes (parameters added/removed/reordered)
- Removed exports or public API functions
- Major refactors affecting multiple files
- Migration-requiring dependency updates
- When detected, adds `BREAKING CHANGE:` footer
## Usage Examples
### Example 1: Feature Addition
**You run:**
```bash
# Stage your changes
git add src/components/UserProfile.tsx
# Ask Claude:
"Generate a commit message for my staged changes"
```
**Claude analyzes:**
```diff
+ export function UserProfile({ userId }: Props) {
+ const user = useUser(userId);
+ return <div>{user.name}</div>;
+ }
```
**Generated message:**
```
feat(user-profile): add user profile component
Implements new UserProfile component that displays user information
based on userId prop. Integrates with useUser hook for data fetching.
```
### Example 2: Bug Fix
**You run:**
```bash
git add src/api/auth.ts
# Ask Claude:
"Create a commit message"
```
**Claude analyzes:**
```diff
- if (token == null) {
+ if (token === null || token === undefined) {
throw new Error('Invalid token');
}
```
**Generated message:**
```
fix(auth): use strict equality check for token validation
Fixes bug where token with value 0 or empty string would incorrectly
pass validation. Now uses strict equality to properly check for null
or undefined values.
```
### Example 3: Breaking Change
**You run:**
```bash
git add src/api/users.ts
# Ask Claude:
"Generate commit message"
```
**Claude analyzes:**
```diff
- export async function getUser(id: string): Promise<User> {
+ export async function getUser(id: string, options?: GetUserOptions): Promise<UserResponse> {
```
**Generated message:**
```
feat(api)!: add options parameter to getUser function
Extends getUser API to accept optional configuration object for
including related data. Return type changed to UserResponse for
better type safety.
BREAKING CHANGE: getUser now returns UserResponse instead of User.
Update all callers to access user data via response.data property.
```
### Example 4: Documentation Update
**You run:**
```bash
git add README.md docs/api.md
# Ask Claude:
"Generate commit"
```
**Generated message:**
```
docs: update API documentation and README
- Add authentication examples to API docs
- Update installation instructions in README
- Fix typos in configuration section
```
### Example 5: Dependency Update
**You run:**
```bash
git add package.json package-lock.json
# Ask Claude:
"Make commit message"
```
**Claude analyzes:**
```diff
- "react": "^17.0.2"
+ "react": "^18.2.0"
```
**Generated message:**
```
build(deps): upgrade react to v18.2.0
Updates React from v17 to v18 for improved concurrent rendering
features and automatic batching. No breaking changes in our usage.
```
## Configuration
### Optional: Customize Commit Style
While this skill uses Conventional Commits by default, you can customize the style in your conversation:
```
"Generate a commit message following Angular style"
"Create a commit using Gitmoji format with emojis"
"Write a detailed commit message with bullet points in the body"
```
### Optional: Set Default Scope
If you're working in a monorepo or specific module:
```
"Generate commit messages with scope 'frontend' for this session"
"All my commits should have scope 'api'"
```
### Optional: Link to Issue Tracker
If your branch name includes issue numbers:
```bash
# Branch: feature/USER-123-add-profile
# Generated message will include:
#
# feat(user-profile): add user profile component
#
# Closes USER-123
```
## Best Practices
### For Best Results
1. **Stage related changes together**: Don't mix features and fixes in one commit
2. **Review the generated message**: Claude generates smart defaults, but you can refine
3. **Add context if needed**: Mention "this fixes a race condition" for better descriptions
4. **Use meaningful branch names**: Branch names help Claude understand context
5. **Keep commits atomic**: One logical change per commit works best
### Tips for Teams
- **Enforce with git hooks**: Use husky + commitlint to validate format
- **Document your scopes**: Maintain a list of valid scopes for your project
- **Review in PRs**: Check commit messages during code review
- **Generate changelogs**: Use `conventional-changelog` to automate release notes
- **Semantic versioning**: Use `semantic-release` to version from commits
## Conventional Commit Format Reference
### Structure
```
<type>[optional scope][optional !]: <description>
[optional body]
[optional footer(s)]
```
### Types
- `feat:` - New feature for users (triggers MINOR version)
- `fix:` - Bug fix for users (triggers PATCH version)
- `docs:` - Documentation only changes
- `style:` - Formatting, missing semicolons, etc. (no code change)
- `refactor:` - Code change that neither fixes a bug nor adds a feature
- `perf:` - Performance improvement
- `test:` - Adding or updating tests
- `build:` - Changes to build system or dependencies
- `ci:` - Changes to CI configuration files and scripts
- `chore:` - Other changes that don't modify src or test files
- `revert:` - Reverts a previous commit
### Breaking Changes
Add `!` after type/scope OR include `BREAKING CHANGE:` in footer:
```
feat(api)!: remove deprecated endpoints
BREAKING CHANGE: The /v1/users endpoint has been removed.
Use /v2/users instead.
```
## Troubleshooting
### Issue: "No staged changes found"
**Cause**: You haven't run `git add` yet.
**Solution**:
```bash
# Stage your changes first
git add .
# Or stage specific files
git add src/components/Button.tsx
# Then ask for commit message
```
### Issue: Generated message is too generic
**Cause**: Changes are ambiguous or too broad.
**Solution**: Provide more context:
```
"Generate a commit message - this change fixes a memory leak in the cache"
"Create a commit - this adds JWT authentication support"
```
### Issue: Wrong change type detected
**Cause**: File patterns don't clearly indicate intent.
**Solution**: Specify the type:
```
"Generate a 'fix' commit message"
"Create a 'refactor' commit for these changes"
```
### Issue: Scope is incorrect
**Cause**: File path doesn't match your project structure.
**Solution**: Specify the scope:
```
"Generate commit with scope 'auth'"
"Create commit message for the API module"
```
### Issue: Want to include co-authors
**Solution**: Ask Claude to add co-author footer:
```
"Generate commit and add co-author: Jane Doe <jane@example.com>"
```
Result:
```
feat(user): add profile page
Co-authored-by: Jane Doe <jane@example.com>
```
## Integration with Tools
### Commitlint
Validate generated messages:
```bash
npm install -g @commitlint/cli @commitlint/config-conventional
# .commitlintrc.json
{
"extends": ["@commitlint/config-conventional"]
}
```
### Husky
Enforce validation on commit:
```bash
npm install -g husky
# .husky/commit-msg
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"
npx --no -- commitlint --edit "$1"
```
### Semantic Release
Automate versioning and changelog:
```bash
npm install -g semantic-release
# Automatically generates:
# - Version numbers from commit types
# - CHANGELOG.md from commit messages
# - Git tags
# - GitHub releases
```
### Conventional Changelog
Generate changelog manually:
```bash
npm install -g conventional-changelog-cli
conventional-changelog -p angular -i CHANGELOG.md -s
```
## Examples of Good vs Bad Commits
### β Bad (Before this skill)
```
update stuff
fix bug
wip
changes
asdf
updated component
```
### β
Good (With this skill)
```
feat(auth): implement JWT token refresh mechanism
Adds automatic token refresh before expiration to prevent
session interruptions. Includes retry logic and error handling.
fix(api): prevent race condition in user data fetch
Adds mutex lock to ensure sequential processing of concurrent
user data requests. Fixes issue where stale data could overwrite
fresh data.
docs(readme): add installation instructions for Windows
Includes PowerShell-specific commands and troubleshooting
section for common Windows installation issues.
```
## Advanced Usage
### Multi-file Commits
When you stage multiple files:
```bash
git add src/components/Button.tsx src/components/Input.tsx src/styles/forms.css
```
Claude will:
1. Identify the common scope (e.g., `forms` or `components`)
2. List major changes in the body
3. Keep the subject line focused on the primary change
### Monorepo Support
For monorepos, specify the workspace:
```
"Generate commit for the @myapp/frontend package"
"Create commit scoped to the api workspace"
```
Result:
```
feat(frontend): add dark mode toggle
or
feat(api): add rate limiting middleware
```
### Branch Name Context
Claude uses your branch name for additional context:
- `feature/USER-123` β Adds "Closes USER-123" footer
- `fix/login-error` β Prefers `fix` type
- `docs/api-reference` β Prefers `docs` type
## Why Conventional Commits Matter
### For Your Team
- **Consistent history**: Easy to scan git log and understand changes
- **Better reviews**: Reviewers know what type of change to expect
- **Faster onboarding**: New team members can follow commit patterns
- **Clear releases**: Know exactly what changed between versions
### For Automation
- **Automated versioning**: Commits drive semantic version bumps
- **Auto-generated changelogs**: Release notes write themselves
- **CI/CD triggers**: Run different pipelines for feat vs fix
- **Breaking change detection**: Automated detection of major versions
### For You
- **Less mental load**: No more "what should I write?"
- **Faster commits**: 30 seconds instead of 3 minutes
- **Better documentation**: Your past self will thank you
- **Professional portfolio**: Clean commit history impresses employers
## Related Resources
- [Conventional Commits Specification](https://www.conventionalcommits.org)
- [Angular Commit Guidelines](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)
- [Semantic Versioning](https://semver.org)
- [Commitlint Documentation](https://commitlint.js.org)
- [Semantic Release](https://semantic-release.gitbook.io)
## Real-World Examples
### Linux Kernel Style (Adapted)
```
fix(mm): prevent use-after-free in page cache
The page cache could reference freed memory under heavy load.
Add proper reference counting to prevent the issue.
Fixes: abc1234 ("mm: optimize page cache")
Reported-by: security@kernel.org
```
### React Repository Style
```
feat(hooks): add useTransition hook
Adds new concurrent rendering hook for deferring state updates.
Includes TypeScript types and comprehensive test coverage.
Related: #18796
```
### Your Projects
This skill adapts to your project's style while maintaining conventional commits structure.
---
**Pro Tip**: After using this skill for a week, you'll start writing better commit messages naturally - it's a great learning tool!
**License**: MIT-0 (Public Domain)
don't have the plugin yet? install it then click "run inline in claude" again.