Git Commit Helper

Helps create atomic, well-formatted commits following conventional commit standards. Automatically analyzes changes to determine if they should be split into multiple commits.

Core Responsibilities

1. Parallel git operations - Run git status and git diff concurrently for speed
2. Smart staging detection - Check if files are already staged, otherwise auto-stage
3. Intelligent diff analysis - Determine if changes should be split into multiple commits
4. Conventional commit messages - Generate properly formatted commit messages
5. Commit attribution - Add Claude Code attribution to commit messages

When to Use This Skill

Use this skill when:

• User explicitly requests commit creation
• Creating commits with proper conventional format
• Analyzing changes to determine if they should be split
• Need to generate meaningful commit messages automatically
• Working with staging area and need guidance

Use direct git commands when:

• User wants to run specific git commands directly
• Debugging git issues
• Complex git operations beyond basic commits

Workflow

1. Gather Information (Parallel)

# Run concurrently for speed
git status & git diff --staged & git diff & git diff --stat

2. Analyze and Decide

Single commit if:

• All changes relate to one purpose
• Changes are tightly coupled
• Splitting would create incomplete features
• Total diff is reasonably sized

Split commits if:

• Different functionality (features vs bug fixes vs refactoring)
• Different subsystems (auth vs API vs UI)
• Different file types (code vs docs vs config)
• Different purposes (implementation vs tests vs dependencies)

3. Stage Strategically

# Stage all (excluding secrets)
git add .

# Stage specific files
git add path/to/file1.js path/to/file2.js

# Stage by pattern
git add src/auth/*

# Stage interactively
git add -p file.js

4. Create Commit

Always use HEREDOC format:

git commit -m "$(cat <<'EOF'
<type>[optional scope]: <description>

[optional body explaining why, not what]

[optional footer: Fixes #123]

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

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

5. Verify

git status    # Verify commit created
git log -1    # Review last commit

Conventional Commit Types

• feat - A new feature
• fix - A bug fix
• docs - Documentation only changes
• style - Code style changes (formatting, semicolons, etc.)
• refactor - Code change that neither fixes a bug nor adds a feature
• perf - Performance improvement
• test - Adding or correcting tests
• build - Build system or external dependencies
• ci - CI configuration files and scripts
• chore - Other changes that don't modify src or test files
• revert - Reverts a previous commit

With scope: feat(auth): add password reset Breaking change: feat!: remove deprecated API (note the !)

Commit Message Rules

Description line:

• Use imperative mood: "add" not "added" or "adds"
• Don't capitalize first letter
• No period at the end
• Keep under 72 characters
• Be specific: ✓ fix: resolve race condition in data sync ✗ fix: bug fix

Body (optional):

• Wrap at 72 characters
• Explain "why" not "what"
• Include motivation and context

Footer (optional):

• Reference issues: Fixes #123, Closes #456, See also: #789
• Breaking changes: BREAKING CHANGE: removed /v1/auth endpoint

Security: Never Commit Secrets

Always exclude:

• .env*, credentials.json, secrets.json
• *.pem, *.key, *.p12, *.pfx
• API tokens, passwords, private keys

If secrets detected: Warn user, suggest .gitignore or environment variables, only proceed if user explicitly confirms

Pre-commit Hook Handling

Standard flow:

1. Attempt commit
2. If hooks fail, read error message
3. Fix issues hooks identified
4. Retry commit

If hooks modify files:

# Check if safe to amend (should show Claude as author, not pushed)
git log -1 --format='%an %ae'
git status

# If safe, amend
git add .
git commit --amend --no-edit

# Otherwise, create new commit
git commit -m "$(cat <<'EOF'
chore: apply pre-commit hook fixes

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

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

Bypass hooks: Only when user explicitly requests --no-verify

Common Patterns

Simple Commit

git status & git diff
git add .
git commit -m "$(cat <<'EOF'
feat: add user dashboard with activity widgets

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

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"
git status

Commit Staged Files Only

git diff --staged
git commit -m "$(cat <<'EOF'
fix: resolve email validation for plus addressing

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

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

Split Commits

# First commit
git add src/auth/*
git commit -m "$(cat <<'EOF'
feat: implement OAuth2 authentication flow

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

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

# Second commit
git add tests/auth/*
git commit -m "$(cat <<'EOF'
test: add OAuth2 flow integration tests

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

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

With Detailed Body

git commit -m "$(cat <<'EOF'
refactor: extract API client configuration to separate module

Moved API client setup logic from individual service files to
centralized config module to reduce duplication and simplify updates.

Fixes #123

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

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

Quick Troubleshooting

• Hooks rejected commit: Read error, fix issues, retry
• Wrong message: git commit --amend -m "new message" (if not pushed)
• Forgot files: git add file && git commit --amend --no-edit (if not pushed)
• Need to split: git reset HEAD~1, then stage and commit separately (if not pushed)
• Committed secrets: git reset HEAD~1, restage without secrets (if not pushed; if pushed, use git-filter-repo)

Best Practices

1. Each commit = one logical change (atomic commits)
2. Test before committing
3. Review diffs before staging
4. Write clear, descriptive messages
5. Commit frequently (small commits > large commits)
6. Don't mix unrelated changes
7. Use conventional format for parseable history
8. Reference issue tracker when relevant

Performance Tips

• Run git commands in parallel when independent
• Use git diff --stat for quick overview before full diff
• Use HEREDOC directly (no temp files)
• Cache staging status to avoid repeated checks

Integration

• Git hooks: Compatible with pre-commit, commit-msg, prepare-commit-msg
• Changelog generators: conventional-changelog, semantic-release, standard-version
• Issue trackers: Reference issues in footers (Fixes #123)

Quick Reference

# Analyze (parallel)
git status & git diff --staged & git diff & wait

# Stage
git add .                           # All files
git add path/to/file1 path/to/file2 # Specific files
git add src/**/*.ts                 # Pattern

# Commit
git commit -m "$(cat <<'EOF'
<type>: <description>

[optional body]

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

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

# Verify
git status && git log -1

# Fix (if not pushed)
git commit --amend --no-edit  # Amend
git commit --amend -m "msg"   # Change message
git reset HEAD~1              # Undo commit

Resources

• Conventional Commits: https://www.conventionalcommits.org/
• Git Documentation: https://git-scm.com/doc
• Git Best Practices: https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project