commit-craft – Writing & Content skill for AI agents

Commit Craft

> Portability: 3 stdlib Python scripts that call git read-only. No network.

> The scripts never stage, commit or push. You do, one group at a time, after the gate passes.

Agents leave large mixed diffs: a feature, a reformat, a dependency bump and a

stray .env, all in one tree. Committed as one blob, that diff cannot be

reviewed, reverted or bisected. This skill turns it into a series where each

commit is one logical change, builds on its own, holds no secrets and says why.

Workflow

# 1 - Plan: which commits, in which order, staged how?
python scripts/commit_planner.py                 # working tree vs HEAD, untracked included
# 2 - For each group: stage exactly its files, then gate what is staged
git add -- <files of group N>                     # or git add -p for MIXED_FORMATTING files
python scripts/secret_gate.py                     # blocks before the commit exists
# 3 - Write the message, lint it, commit
python scripts/message_linter.py -m "<message>" --staged && git commit -m "<message>"
# 4 - Before push: the whole series, and proof every commit builds
python scripts/message_linter.py --range @{upstream}..HEAD
git rebase -x "<test command>" @{upstream}

Step 1 groups files: manifest with lockfile, pure moves, whitespace-only

files, each module's changes with their tests, then docs and CI. It holds back

.env, keys and tfstate (exit 4), flags files that mix formatting with real

hunks, and flags a move whose callers' import edits sit in another group, since

that commit would not build. It never picks feat vs fix: decide from what the change does.

Step 2 scans only the added lines of what is staged: provider-shaped

tokens, high-entropy values assigned to key/secret/token/password, sensitive

files and conflict markers. Output is redacted. A false positive is waived in

.commit-craft-allow by fingerprint or path, with a reason.

Step 3 blocks vague subjects ("fix", "update"), subjects over 72 characters,

no blank line after the subject, and a change of 40+ lines or 4+ files with no

body. It enforces Conventional Commits only if the repo already uses them.

Step 4 also blocks fixup!/squash!/WIP commits and warns on duplicates and

revert pairs. Install assets/hooks/ to run steps 2 to 4 on every commit and push.

Hard rules

• Never git add -A or git add . on a mixed tree. Stage each group by name or by hunk.
• A blocked gate means no commit. Remove the value and load it at runtime. Never --no-verify, never waive a real secret.
• A pushed secret is rotated first. Deleting it in a new commit leaves it in history (references/secret_response.md).
• Each commit builds. Tests ride with their change; moves carry their callers.
• The body says why. The diff already says what.
• Rewrite only unpushed history. Rebasing or amending shared commits is the user's call.

Scripts

| Script | Role | Exit codes |

|---|---|---|

| scripts/commit_planner.py | Groups, order, staging commands, MOVE/MIXED/SIZE flags | 0 one commit · 2 split · 3 bad input · 4 secrets file held back |

| scripts/secret_gate.py | Staged or range scan for credentials, sensitive files, conflict markers | 0 · 2 warnings · 3 · 4 blocked |

| scripts/message_linter.py | One message (-m, --message-file) or a series (--range) | 0 · 2 warnings · 3 · 4 blocked |

All support --help, --sample and --output json.

References and assets

• [references/commit_series_design.md](references/commit_series_design.md): split, order and verify, with sources (7)
• [references/message_discipline.md](references/message_discipline.md): subject, why-body, breaking changes, trailers (7)
• [references/secret_response.md](references/secret_response.md): what the gate catches, its limits, and the leak response order (7)
• [assets/hooks/](assets/hooks/): pre-commit, commit-msg, pre-push
• [assets/commit-craft-allow.example](assets/commit-craft-allow.example): waiver format
• [assets/series_checklist.md](assets/series_checklist.md): pre-push sign-off