Conventional Commit Batcher
Use this skill to turn a messy working tree into clean, reviewable Conventional Commit history.
Commit Interception (MANDATORY)
This skill MUST be activated for ANY commit-related operation, including:
- user asks to commit, stage, or push changes
- user asks to "save" or "check in" code
- any workflow that would result in
git add,git commit, orgit push
Do NOT run git add or git commit directly without going through this skill's workflow.
Use This Skill When
- any commit operation is performed through an agent (automatic interception)
- changes from different intents are mixed in one branch
- you want a plan-first commit process before opening a PR
- you need reliable Conventional Commit messages across team and agents
Skip This Skill When
- the change is tiny and clearly single-intent
- you only need one quick commit without batching
Note: even when the skill could be skipped, if it is installed, the agent will still run the workflow and safety gates. The result may be a single batch, which is fine.
Default Behavior: Auto-Execute
By default, the skill inspects changes, splits into logical batches, runs safety gates, and commits directly — without waiting for user confirmation.
To see the plan before execution, explicitly ask:
Show me the commit plan first before executing.High-Success Prompt (Plan-First Mode)
Use this prompt only when you want to review the plan before execution:
Inspect my current git changes and split them into logical Conventional Commit batches.
Output a full Commit Plan first.
Do not run git add or git commit until I confirm the plan.
After confirmation, execute each batch one by one.Output Contract
In auto-execute mode (default), the agent outputs a brief per-batch summary as each batch is committed.
In plan-first mode (user requested), the agent outputs the full plan before any staging/commit:
Commit Plan
Batch #1: <type(scope): subject>
Intent: <why this batch exists>
Files/Hunks:
- <path> (...)
Staging commands:
- git add ...
Commit command:
- git commit -m "..."Required Behavior
- Always load
references/core-rules.mdfirst. - Treat
references/core-rules.mdas the single source of truth. - Run
python3 scripts/precommit_safety_gate.pybefore every commit attempt when Python is available; otherwise run the equivalent manual gate checks fromreferences/core-rules.md. - Run the sensitive-data gate before every commit and require explicit user confirmation if risky files/hunks are detected.
- When any gate reports risk, include triggered file paths and brief evidence in user-facing output, plus a concrete "please review" suggestion.
- Run the
.gitignore/local-artifact gate before every commit and require explicit user confirmation if suspicious files are present. - Run branch/conflict/large-file/empty-stage safety checks before every commit.
- Never skip commit-time checks with
--no-verify. - If check/hook fails, stop and report concise diagnostics.
Entrypoints
- Codex skill:
SKILL.md - Codex repo loader:
AGENTS.md - Claude:
CLAUDE.md,.claude/agents/conventional-commit-batcher.md,.claude/commands/commit-batch.md - Kiro:
.kiro/agents/conventional-commit-batcher.json,.kiro/steering/commit-batching.md - Shared skill (Kimi / Qwen / Gemini):
.agents/skills/conventional-commit-batcher/SKILL.md - Shared subagent (Qwen / Gemini):
.agents/agents/conventional-commit-batcher.md - OpenAI:
agents/openai.yaml
References
- Canonical rules:
references/core-rules.md - Commit plan examples:
references/plan-examples.md - Commit batching guidance:
references/commit-batching-guide.md - commit-msg hook example:
references/commit-msg-hook-example.md - Agent setup docs:
- references/codex-setup.md - references/claude-setup.md - references/kiro-setup.md - references/kimi-setup.md - references/qwen-setup.md - references/gemini-setup.md
- Validator script:
scripts/validate_conventional_commit.py - Safety gate script:
scripts/precommit_safety_gate.py - Validator tests:
scripts/test_validate_conventional_commit.py - Safety gate tests:
scripts/test_precommit_safety_gate.py