Commit Skill

Creates well-formatted commits following conventional commit standards with emoji prefixes.

When to Use

User says "commit", "commit these changes", or uses /commit
After code changes are ready to be committed
Need help with commit message formatting
Want automatic detection of multi-concern changes

Core Features

GPG signing with cached passphrase (if $GPG_PASSPHRASE set)
Staged vs unstaged detection - commits only staged files when present
Split suggestions - analyzes diffs for multiple logical changes
Conventional commits - <emoji> <type>: <description> format
Pre-commit hook integration - respects Husky/other hooks
Always --signoff - DCO compliance

Process

⚠️ CRITICAL: ALWAYS start with Step 1 (Environment Check) before attempting any commit

1. Environment Check (MANDATORY FIRST STEP)

MUST cache GPG passphrase if available

# If GPG_PASSPHRASE is set, cache it to gpg-agent
if [ -n "$GPG_PASSPHRASE" ]; then
  gpg --batch --pinentry-mode loopback \
      --passphrase-file <(echo "$GPG_PASSPHRASE") \
      --clearsign >/dev/null 2>&1 <<< "test" && echo "✅ GPG passphrase cached" || echo "❌ GPG cache failed"
else
  echo "⚠️  GPG_PASSPHRASE not set - GPG signing will prompt for passphrase (and fail in non-interactive environment)"
fi

Why this matters

GPG_PASSPHRASE purpose: Allow GPG to sign automatically without interactive password prompt
If GPG_PASSPHRASE is set → Must cache first, otherwise git commit --gpg-sign will fail
If GPG_PASSPHRASE not set → GPG will attempt interactive password prompt (fails in Claude Code environment)

GPG signing decision

Whether to use --gpg-sign should be determined by project policy or git config
In this project: always use --gpg-sign (assumes GPG is configured)

When committing

# Always use --gpg-sign (passphrase is cached if GPG_PASSPHRASE was set)
git commit --signoff --gpg-sign -m "..."

2. Analyze Changes

git status --short

# Prefer staged files if any exist
if ! git diff --staged --quiet; then
  git diff --staged --stat    # Staged changes
else
  git diff HEAD --stat        # All changes
fi

3. Multi-Concern Detection

Suggest split if:

Different patterns: src/ + test/ + docs/
Mixed types: feat + fix + docs
Unrelated concerns: auth logic + UI styling
Large changeset: >500 lines

Ask user

Multiple concerns detected:
1. Auth changes (src/auth/*)
2. UI updates (src/components/*)
3. Docs (README.md)

Split into 3 commits?
- ✨ feat: add JWT authentication
- 💄 style: update login UI
- 📝 docs: update auth documentation

[split/all]

4. Create Commit

Format: <emoji> <type>: <description>

Rules

Imperative mood ("add" not "added")
First line <72 chars
Atomic (single purpose)
Use body for "why" if needed

git commit --signoff ${USE_GPG:+--gpg-sign} -m "<emoji> <type>: <description>"

5. Handle --no-verify

If user requests --no-verify:

⚠️  Requested to skip pre-commit hooks.

Bypasses: linting, tests, formatting
Reason: [ask user]

Approve? [yes/no]

Only proceed if confirmed.

Commit Types & Emoji

Type	Emoji	Use Case
feat	✨	New feature
fix	🐛	Bug fix
docs	📝	Documentation
style	💄	Formatting, styling
refactor	♻️	Code restructure
perf	⚡	Performance
test	✅	Tests
chore	🔧	Build/tools
ci	🚀	CI/CD
security	🔒️	Security fix
build	🏗️	Build system
revert	⏪️	Revert changes
wip	🚧	Work in progress

Extended emoji map

Split Decision Examples

❌ Bad - Mixed concerns

+ src/auth/login.ts (feat)
+ src/components/Button.css (style)
+ README.md (docs)

Split into: 3 separate commits

✅ Good - Single concern

+ src/auth/login.ts
+ src/auth/middleware.ts
+ tests/auth.test.ts

One commit: ✨ feat: add authentication

❌ Bad - Mixed types

+ Add export feature (feat)
+ Fix date bug (fix)

Split into: 2 commits by type

❌ Bad - Large multi-feature

300+ lines: auth system
200+ lines: UI components
150+ lines: database

Split into: 3 commits by feature

Critical Rules

NEVER

❌ Add Claude signature to commits
❌ Commit without checking staged status
❌ Skip split suggestions for multi-concern
❌ Use past tense ("added" → "add")
❌ Make first line >72 chars
❌ Bypass hooks without asking
❌ Attempt git commit before running GPG cache command

ALWAYS

✅ FIRST: Run Environment Check (Step 1) to cache GPG passphrase
✅ Use --signoff flag (always)
✅ Use --gpg-sign flag (always, passphrase is cached in Step 1)
✅ Analyze diff before commit
✅ Suggest splits when appropriate
✅ Use imperative mood
✅ Pick correct emoji + type
✅ Ask approval for --no-verify

Integration Notes

With CLAUDE.md

CLAUDE.md references this skill: "Use /commit or say 'commit changes'"

With spec-kit

Reference planning docs in commit body:

✨ feat: add user authentication

- JWT token validation
- Protected routes middleware
- Tests cover happy/error paths

Related to Stage 2 of PLAN.md (User Story 1.2)

With Husky

Hooks run automatically unless --no-verify used (requires approval).

Example Sessions

Simple commit

User: "commit these changes"

Process:
1. Check GPG ✓
2. Analyze: src/auth/login.ts (modified)
3. Single concern ✓
4. Create: ✨ feat: add login endpoint
5. Execute: git commit --signoff --gpg-sign -m "..."

Split required

User: "commit"

Process:
1. Detect: auth + UI + docs
2. Suggest split (3 commits)
3. User confirms "split"
4. Commit each separately with proper emoji/type

Skip hooks

User: "/commit --no-verify"

Response:
"⚠️ Skip hooks? Bypasses linting/tests.
Reason: [wait]"

User: "hotfix for production"

Action: Proceed with --no-verify

Troubleshooting

GPG fails

echo $GPG_PASSPHRASE  # Check set
gpg --clearsign <<< "test"  # Test manually
# If fails: commit without --gpg-sign

Hook fails

Check output → fix issue → retry Critical case only: ask about --no-verify

No changes

git status
# No changes: inform user
# Unstaged only: "Stage files first?"

Progressive Disclosure

Keep this main file under 500 lines. For extensive reference:

Emoji cheatsheet → See emoji-reference.md (if needed)
Advanced patterns → See advanced-commits.md (if needed)

Current approach: All essential info in this file for immediate use.