git-commit-composer

Git Commit Composer

Instructions

When to Invoke This Skill

• Ready to commit changes after implementation
• Need to create descriptive commit message
• Following semantic commit conventions
• Linking commits to issues or PRs

Commit Message Format

Structure

<type>: <brief description>

<detailed explanation of what changed and why>

<footer with issue links and metadata>

Components

Type (required):

• feat - New feature
• fix - Bug fix
• chore - Maintenance, dependencies, tooling
• docs - Documentation changes
• refactor - Code restructuring without behavior change
• test - Test additions or modifications
• perf - Performance improvements
• style - Code style/formatting (no logic change)

Brief Description (required):

• Imperative mood: "add", not "added" or "adds"
• Lowercase start
• No period at end
• Maximum 50 characters
• Describe what the commit does

Detailed Explanation (recommended):

• Explain WHAT changed and WHY
• Don't explain HOW (code shows that)
• Use bullet points for multiple changes
• Wrap at 72 characters per line

Footer (optional):

• Issue links: Fixes #123, Resolves #456, Closes #789
• Breaking changes: BREAKING CHANGE: describe the change
• Co-authors: Co-Authored-By: Name <email>
• Tool attribution: 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Standard Workflow

1. Review Changes

   git status
   git diff
   

2. Analyze Changes

   • Determine commit type
   • Identify main purpose
   • Note secondary effects
   • Find related issues

3. Compose Message Follow the format above

4. Create Commit

   git commit -m "$(cat <<'EOF'
   <type>: <brief description>
   
   <detailed explanation>
   
   <footer>
   EOF
   )"
   

Best Practices

Good Brief Descriptions:

• feat: add user authentication with JWT
• fix: resolve race condition in websocket handler
• chore: update dependencies to latest versions
• docs: add API endpoint documentation

Bad Brief Descriptions:

• feat: added some new features (too vague)
• fix: Fixed a bug (not descriptive)
• update (missing type)
• FEAT: Add Feature (wrong capitalization)

Good Detailed Explanations:

Add JWT-based authentication to protect API endpoints

- Implement token generation and validation
- Add middleware to verify tokens on protected routes
- Store refresh tokens in database
- Add token expiration and renewal logic

This ensures only authenticated users can access sensitive data.

Bad Detailed Explanations:

Made some changes to auth

Commit Message Templates

Feature Commit

feat: add dark mode toggle

Implement dark mode toggle in user settings with:
- Theme preference stored in localStorage
- CSS variable switching for colors
- Smooth transitions between themes

Fixes #42

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Bug Fix Commit

fix: resolve websocket race condition

Fix race condition where messages could be sent before connection
fully established:
- Add connection ready flag
- Queue messages during connection
- Flush queue once connected

Fixes #156

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Chore Commit

chore: update Python dependencies

Update uv.lock with latest package versions:
- fastapi 0.104.0 -> 0.109.0
- uvicorn 0.24.0 -> 0.27.0
- pydantic 2.5.0 -> 2.6.0

All tests passing with updated versions.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Refactor Commit

refactor: extract message processing into handlers

Split monolithic message processor into specialized handlers:
- SystemMessageHandler
- AssistantMessageHandler
- UserMessageHandler
- ResultMessageHandler

No behavior changes, improved maintainability.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Multiple Commits vs Single Commit

Use Multiple Commits When:

• Changes are logically separate
• Each commit works independently
• Different types (feat + docs)

Use Single Commit When:

• Changes are tightly coupled
• Breaking them apart doesn't make sense
• Implementing single issue/feature

Amending Commits

When to Amend:

• Forgot to include a file
• Typo in commit message
• Small addition to last commit
• Commit not yet pushed

How to Amend:

git add <forgotten-files>
git commit --amend --no-edit

When NOT to Amend:

• Commit already pushed to remote
• Other developers have the commit
• Would rewrite shared history

Examples

Example 1: Feature implementation

Changes: Added user profile page with avatar upload
Action:
1. Review changes: git diff
2. Identify type: feat (new feature)
3. Compose:
   - Brief: "add user profile page with avatar upload"
   - Detail: List components added, functionality
   - Footer: Fixes #42
4. Commit with formatted message

Example 2: Bug fix

Changes: Fixed null pointer error in login handler
Action:
1. Identify type: fix (bug fix)
2. Brief: "resolve null pointer in login handler"
3. Detail: Explain the bug and how it was fixed
4. Footer: Fixes #89
5. Commit

Example 3: Multiple related changes

Changes: Updated deps + fixed compatibility issue
Decision: Single commit (changes are coupled)
Action:
1. Type: chore (dependency update)
2. Brief: "update dependencies and fix compatibility"
3. Detail: List updates + explain compatibility fix
4. Commit together

Example 4: Separate concerns

Changes: New feature + unrelated docs update
Decision: Two commits (logically separate)
Action:
1. Stage feature files: git add src/
2. Commit feature: feat message
3. Stage docs: git add docs/
4. Commit docs: docs message