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, or git 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.md first.
Treat references/core-rules.md as the single source of truth.
Run python3 scripts/precommit_safety_gate.py before every commit attempt when Python is available; otherwise run the equivalent manual gate checks from references/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