| name | split-commit |
| description | Split an existing commit or PR into smaller reviewable pieces through a one-hunk patch queue. Use when extracting part of a commit, splitting a commit into multiple commits, or splitting PR changes from one or more source commits without starting from direct source edits. |
Split Commit
Use this skill when the user asks to split an existing commit or PR into smaller pieces through an explicit patch queue.
Requirements
- Start with a clean worktree and index unless the user explicitly says otherwise.
- Do not start by editing source files directly. Use the generated one-hunk patches as the extraction source of truth.
- After setup, do not enumerate
todo/ or read patch files directly. Inspect patches only through scripts/next-patch.sh.
- Process the queue strictly in order. Do not inspect later entries before the current patch leaves
todo/.
- Every patch must leave
todo/ through exactly one state: applied/, skipped/, partially-applied/, or merge-conflicted/.
- For
partial, keep the moved patch as the audit artifact, then reduce that patch to the in-scope subset only. Do not introduce edits that are not already present in the surfaced patch.
- Validate the repo state before creating final commits.
Scripts
scripts/setup-split-patches.sh
scripts/next-patch.sh
scripts/process-patch.sh
Workflow
- Create the queue from a source commit or revision range.
- Run
scripts/next-patch.sh to get the next patch path and full patch content.
- Decide only for that surfaced patch:
apply, skip, or partial.
- Run
scripts/process-patch.sh for that action.
- If the action is
partial, perform the scoped manual edit immediately and keep only the in-scope subset from that patch.
- If a patch reaches
merge-conflicted/, resolve the reported conflicts before continuing.
- Repeat until
scripts/next-patch.sh prints All patches are processed..
Example loop
scripts/setup-split-patches.sh --source 4a95362 --repo /abs/path/to/repo
scripts/next-patch.sh --workdir /tmp/split-commit.ABC123
scripts/process-patch.sh \
--workdir /tmp/split-commit.ABC123 \
--patch /tmp/split-commit.ABC123/todo/003-file.patch \
--action apply
scripts/next-patch.sh --workdir /tmp/split-commit.ABC123
scripts/process-patch.sh \
--workdir /tmp/split-commit.ABC123 \
--patch /tmp/split-commit.ABC123/todo/004-file.patch \
--action partial
scripts/next-patch.sh --workdir /tmp/split-commit.ABC123
Notes
scripts/setup-split-patches.sh supports --source <commit-ish> and also accepts explicit revision ranges.
scripts/next-patch.sh is the only queue inspection entry point and is also the completion check.
scripts/process-patch.sh --action apply tries normal apply first, then falls back to git apply --3way.