Smart Git Commit Skill

Produces gold-standard Git commits: tested, atomic, secure, documented, and traceable. Follow every phase below in order. Never skip phases unless the user explicitly says so.

<!-- line-limit: 500 -->

Phase 0 — Read Project Rules

Check for CLAUDE.md, .gitmessage, .git/COMMIT_TEMPLATE at repo root. If found, those rules override this skill's defaults.

cat CLAUDE.md 2>/dev/null && echo "→ Found CLAUDE.md"
cat .gitmessage 2>/dev/null && echo "→ Found .gitmessage"

Show what rules were loaded before proceeding.

Phase 1 — Diff Analysis

Run full diff analysis before touching git add:

git status
git diff --stat          # which files, how many lines
git diff                 # full diff for small changesets
git log --oneline -5     # recent commit context

Categorize every changed file:

If files span more than one category → flag for atomic split in Phase 4. Read references/atomic-patterns.md if split is needed.

Phase 2 — Security Scan (Never Skip)

Run the automated security scanner:

bash scripts/scan-secrets.sh

• Exit 0 → show "✓ Clean" and continue
• Exit 1 → HARD STOP. Show findings. Do not proceed until clean.

If secrets found:

1. git reset HEAD <file> to unstage
2. Replace with env var or placeholder
3. Add to .gitignore if needed
4. Rotate exposed credentials if already pushed

Read references/security-rules.md for the full pattern list.

Phase 3 — Test Gate (Never Skip)

Auto-detect and run the project's test suite:

bash scripts/detect-test-runner.sh

• status = "pass" → show test count and continue
• status = "fail" → HARD STOP. Fix failures first, then commit fix + feature together.
• status = "not_found" → warn user, ask if they want to proceed anyway

Supported runners: npm test, pytest, cargo test, go test, make test, rspec, mix test, gradle, ctest.

Phase 4 — Atomic Split Decision

If Phase 1 found multiple concerns:

bash scripts/split-commits.sh

Show the proposed split plan. Execute each commit group in sequence (Phases 5-7 repeat per group).

If single concern: proceed directly to Phase 5.

Read references/atomic-patterns.md for splitting strategies.

Phase 5 — Commit Message Construction

Use the 5-part format for every commit. No exceptions.

<type>(<scope>): <imperative summary — max 72 chars>

CONTEXT: <what state existed BEFORE this change — past tense>
CHANGE:  <exactly what was done — present tense, specific>
WHY:     <business or technical reason — not obvious from the code>
IMPACT:  <what this enables/unblocks, or "No breaking changes">

<footers>

Summary line rules

• Imperative mood: "add" not "added", "fix" not "fixing"
• No period at end
• Under 72 characters
• Types: feat fix perf security refactor test docs chore hotfix revert release

Field rules

Example

fix(payments): prevent double-charge on Stripe webhook retry

CONTEXT: Stripe delivered webhooks twice under high load due to 30s
         application timeout, causing duplicate charges.
CHANGE:  Adds idempotency_key (order_id + unix_ts hash) to all Stripe
         charge requests.
WHY:     Stripe's API natively deduplicates on idempotency keys — simpler
         than Redis-based deduplication.
IMPACT:  Eliminates billing support tickets for duplicate charges.

Closes #301

Read references/message-examples.md for 15 full examples.

Phase 6 — Issue and Ticket Linking

Auto-detect from branch name:

git branch --show-current | grep -oE '[0-9]+'

Check for open issues:

gh issue list --state open 2>/dev/null | head -20

Use the correct footer keyword:

If no issue found, ask user before proceeding.

Phase 7 — Execute Commits

Stage selectively — never git add . blindly:

git add <specific files or directories>
git diff --cached --stat   # verify before committing
git commit -m "<subject>" \
  -m "CONTEXT: ...
CHANGE:  ...
WHY:     ...
IMPACT:  ..." \
  -m "<footers>"
git show --stat HEAD       # confirm after

Phase 8 — Push Strategy

Never push directly to main or develop. Always push to feature branch:

git push origin HEAD
git push --set-upstream origin <branch>   # if new branch

Show commits being pushed:

git log --oneline origin/main..HEAD

Phase 9 — PR Creation

If on a feature branch after push:

bash scripts/create-pr.sh

• Always creates as draft — user promotes when ready
• Show PR URL after creation

Phase 10 — Release Tagging

Triggers on: "release", "ship", "version bump", "tag this"

bash scripts/generate-changelog.sh

Then:

1. Read current version from package.json, pyproject.toml, Cargo.toml
2. Bump version in the appropriate file
3. Commit: chore(release): bump version to vX.Y.Z (with 5-part format)
4. Tag: git tag -a vX.Y.Z -m "Release vX.Y.Z"
5. Push: git push && git push --tags

Read references/release-workflow.md for full semver guide.

Quick Reference