conventional-commit-batcher

中文文档

Turn mixed local changes into clean, reviewable Conventional Commit batches.

Automatic Commit Interception

Once installed, this skill automatically intercepts ALL commit-related operations — not just explicit "batch my commits" requests. When the agent detects any intent to git add, git commit, or git push, it MUST follow the plan-first workflow before executing any git command.

This means:

• Asking the agent to "commit my changes" triggers the full workflow.
• The agent splits changes into logical batches, runs safety gates, and commits directly — no confirmation needed by default.
• To review the plan before execution, explicitly ask the agent to show the plan first.
• Safety gates (sensitive data, conflict markers, protected branch, etc.) still require user confirmation when triggered, regardless of execution mode.

This behavior is enforced across all supported platforms (Codex, Claude Code, Kiro, Kimi, Qwen, Gemini, OpenAI) through their respective entrypoint files.

Why Use This Skill

• Plan-first workflow prevents accidental mixed commits.
• Clear batch boundaries make review, revert, and git bisect safer.
• Commit messages stay standards-compliant without manual policing.
• Built-in safety gates catch risky commits before they happen.

Who This Is For

• Developers with a messy working tree before opening a PR.
• Teams that want cleaner commit history for release/changelog tooling.
• Agent-driven workflows that need deterministic commit hygiene.

30s Quick Try

A) Install as an Agent Skill (recommended)

npx skills add cnkang/conventional-commit-batcher
npx skills list

Then ask your agent:

I have mixed changes in my working tree. Commit them with proper Conventional Commit messages.

The agent will automatically inspect, split, and commit. To review the plan before execution instead:

I have mixed changes in my working tree.
Show me the commit plan first before executing.

B) Use git hooks (no agent required)

cat > .git/hooks/commit-msg <<'HOOK'
#!/usr/bin/env bash
set -euo pipefail

MSG_FILE="$1"
SCRIPT_PATH="scripts/validate_conventional_commit.py"

if [ ! -f "$SCRIPT_PATH" ]; then
  echo "[commit-msg] validator not found: $SCRIPT_PATH"
  exit 1
fi

python3 "$SCRIPT_PATH" \
  --file "$MSG_FILE" \
  --max-subject-length 72 \
  --max-header-length 100
HOOK

chmod +x .git/hooks/commit-msg

cat > .git/hooks/pre-commit <<'HOOK'
#!/usr/bin/env bash
set -euo pipefail

python3 scripts/precommit_safety_gate.py
HOOK

chmod +x .git/hooks/pre-commit

What You Should Expect

By default, the skill auto-executes: it inspects changes, splits into logical batches, runs safety gates, and commits directly. After each batch, it reports what was committed.

If you want to review the plan before execution, explicitly ask:

Show me the commit plan first before executing.

In plan-first mode, the skill outputs the full plan and waits for your confirmation:

Commit Plan
Batch #1: feat(scope): ...
Intent: ...
Files/Hunks:
- ...
Staging commands:
- git add ...
Commit command:
- git commit -m "feat(scope): ..."

Built-In Safety Gates

The skill includes pre-commit guards for common beginner mistakes:

• secret/sensitive data accidentally staged
• local or generated files that should stay out of history (.gitignore drift)
• commits on protected/release branches by mistake
• unresolved merge conflict markers
• unexpected binary/large artifacts
• empty staged commit attempts

These checks are executed by scripts/precommit_safety_gate.py before each commit attempt:

python3 scripts/precommit_safety_gate.py

• exit 0: pass
• exit 2: explicit user confirmation required (rerun with matching --allow-* flags after confirmation)
• exit 3: hard block (must be fixed before commit)

If Python is unavailable, the agent must run the equivalent git diff/git status manual checks from references/core-rules.md and enforce the same decisions.

Why Scripts + No-Python Fallback

• No hard Python dependency: Python script is preferred, not mandatory.
• Why the script exists: it makes checks programmatic, regression-testable, and reusable in hooks/CI.
• If Python is not available: agent runs the same gate logic directly with git commands from references/core-rules.md, checks every gate one by one, and reports/block decisions in the same way.
• In both modes, when sensitive indicators are found, output includes triggered file paths, snippet evidence, and a "please review these files" suggestion.

When To Use / Skip

Use it when:

• any commit operation is performed through an agent (automatic interception)
• one branch contains mixed intents (feat + fix + docs + style)
• you need reviewable commit boundaries before PR
• you want consistent Conventional Commit history across contributors

Skip it when:

• you only have one tiny, single-intent change
• commit history hygiene is not relevant for the task

Note: even when the skill could be skipped, if it is installed, the agent will still produce a Commit Plan and run safety gates. The plan may contain only a single batch, which is fine.

Quick Start Paths

1. Agent flow: load this skill and follow references/core-rules.md.
2. Validator CLI (commit header): python3 scripts/validate_conventional_commit.py "feat(scope): add ...".
3. Safety gate CLI (6 pre-commit checks): python3 scripts/precommit_safety_gate.py.
4. No-Python fallback: run manual gate commands in references/core-rules.md.
5. Hook flow: use the script above (or references/commit-msg-hook-example.md).

Commit Message Language Policy

• Default language is English for commit message text (subject/body/footer).
• If a user explicitly asks for another language, text in subject/body/footer may use that language.
• Conventional Commit syntax tokens stay standard and untranslated: type, optional scope, !, and BREAKING CHANGE:.
• Canonical enforcement lives in references/core-rules.md.
• This section is a non-authoritative summary; references/core-rules.md is the single source of truth.

Commit Body Best Practices

• Keep body optional: add it when the header is not enough.
• Prefer brief, high-signal context (what changed and why it matters).
• Avoid verbose/noisy text that does not help reviewers.
• For tiny or obvious changes, an empty body is acceptable.

Agent-Specific Setup

Use these docs only for tool-specific setup details:

• Codex: references/codex-setup.md
• Claude Code: references/claude-setup.md
• Kiro CLI: references/kiro-setup.md
• Kimi CLI: references/kimi-setup.md
• Qwen Code: references/qwen-setup.md
• Gemini CLI: references/gemini-setup.md

Core Rule Source

All entrypoints delegate to one canonical rule file:

• references/core-rules.md

Community and Feedback

• Bug reports and feature requests: GitHub Issues (.github/ISSUE_TEMPLATE/)
• Product discussion and usage ideas: GitHub Discussions

License

Apache-2.0