Use when the user asks to split a goal across Claude, Codex, or Gemini (gemini requests are rerouted - lane deprecated); plan a multi-agent run; break work into parallel agent tasks; or decompose a large task that needs bounded context handoffs. This is the **generic**
Installs just this skill. Get the whole plugin for auto-invocation.
โก How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/agent-task-splitter
๐๏ธ Context preview
The summary Claude sees to decide when to auto-load this skill.
Use when the user asks to split a goal across Claude, Codex, or Gemini (gemini requests are rerouted - lane deprecated); plan a multi-agent run; break work into parallel agent tasks; or decompose a large task that needs bounded context handoffs. This is the **generic**
๐ Stats
Stars16
Forks4
LanguagePython
LicenseMIT
๐ฆ Ships with agent-collab-workspace
</> SKILL.md
agent-task-splitter.SKILL.md
---name: agent-task-splitter
description: Use when the user asks to split a goal across Claude, Codex, or Gemini (gemini requests are rerouted - lane deprecated); plan a multi-agent run; break work into parallel agent tasks; or decompose a large task that needs bounded context handoffs. This is the **generic** multi-agent task splitter โ writes `.coord/plan.yml` (a DAG) plus per-agent task files. NOT for research-domain routing that touches `.research/`, `.paper/`, or Zotero/Obsidian/NotebookLM ingest pipelines โ for those, use `research-hub-multi-ai` instead (different artifact `.coord/multi_ai_plan.md`, research-hub-aware reconciliation).
---# agent-task-splitter
Bridge between **a high-level goal** and **the multi-agent execution
pipeline**. You write `.coord/plan.yml` (the DAG) and the per-agent
task files. The delegate skills (`codex-delegate`; historically
`gemini-delegate`) invoke the agents using those task files. The
reconciler reads what they produce.
This skill **does not invoke any agent**. It only plans and writes
files.
> **DEPRECATION + REROUTE (2026-06-18, updated 2026-07-10): the Gemini
> lane is DEAD โ it fails closed. Never emit `agent: gemini` tasks.**
> Reroute what used to go there:
>
> | Used to route to `gemini` | Route now |
> |---|---|
> | CJK / bilingual judgment, ่ชๆ, long-form writing | `claude` (inline โ judgment stays with the orchestrator) |
> | Bulk mechanical CJK (mirror sync, term sweeps) | `codex` |
> | Long-context reading + synthesis | `claude` inline, or `claude-cheap` when the reading is extraction/transcription-shaped |
> | Second-opinion review of generated output | `claude` (a review is an honesty-critical task โ never a cheap tier) |
> | Antigravity CLI (`agy`) via `antigravity-delegate` | PROMOTED 2026-07-11: pre-registered k=5 reliability gate 5/5 (mc12: fresh sandbox per trial, decoy untouched, judgment question escalated verbatim, zero git ops) on top of the n=1 capability probe (mc11, 2026-07-10) โ routable for bounded mechanical subtasks like `codex` / `claude-cheap`; cheap-tier guardrails unchanged (never reviews, completion verdicts, governance, or anything ambiguous) |
>
> The `gemini` value remains PARSE-ONLY so reconcilers can read
> historical plans; ยง6b is retained as a legacy reference.
## Why use this instead of hand-rolling briefs
The supervisor (Claude) writing 2-3 brief files by hand looks cheap but
costs token + drift in two specific ways:
| Hand-rolled briefs | This skill |
|---|---|
| Same context block (file paths, conventions, in-scope list) repeated across 3 task files โ 3ร redundant token cost in main session. | Splitter writes once into `.coord/plan.yml`, references it from each task file. |
| Subtle drift between briefs ("Codex was told to update README, Gemini was told to mirror Stage 6" โ but Codex's scope quietly included Stage 6 too). F11 incident shipped because of this. | Splitter computes the file-scope set once and propagates the disjoint partition. |
| Operator forgets which agent gets which task type (codex for mechanical, gemini for long-context CJK). | Routing rules baked in โ same agent gets the same shape of work every time. |
### Measured impact (real dogfood, 2026-05-14)
| Setup | Main session tokens | Notes |
|---|---|---|
| **With splitter** (R2 + R4 combined: 2 parallel Codex + 1 mirror sync Gemini) | ~9k tokens (R2 ~5k + R4 ~4k, measured) | Splitter wrote 5 KB of plan.yml + briefs; main session read only structured summaries |
| **Hand-rolled equivalent** (estimated counterfactual) | ~107-127k tokens (R2 control ~37k + R4 control ~70-90k) | Operator inlines all context per brief, parses each agent's raw stdout, reconciles by hand |
| **Saving** | **~12-14ร** combined (R2 ~7ร + R4 ~17-22ร per round) | Plus the splitter's disjoint-scope partition prevented F11-class drift |
The skill earns its keep when โฅ 2 subtasks go to different agents (or
same agent in parallel). For 1-shot delegation, call the delegate skill
directly.
### Anti-patterns this skill prevents
- **F11** (cross-agent scope creep): Agent A sweeps a rule into files
that were Agent B's responsibility. Prevented by `.coord/plan.yml`'s
explicit `files_in_scope` partition per task.
- **F14** (skipping the splitter for "small enough" 2-agent runs):
Operator decides to hand-roll because "it's only 2 tasks", and the
drift catches them later. The CLAUDE.md template below makes the
trigger mechanical: โฅ 2 parallel delegates โ splitter is mandatory,
no judgment call.
### CLAUDE.md snippet to enforce routing
```markdown
## Multi-agent routing rule (enforced)
If a single round needs โฅ 2 delegate agents running in parallel (e.g.,
codex + claude-cheap, or 2 codex on independent subtasks): invoke
goal: "Refactor the auth module into plugin-based architecture"
budget:
tokens: 200000 # optional, gate skill checks against this
duration_min: 60 # optional advisory
context_policy:
main_session_token_budget: 3000
task_packet_token_budget: 6000
result_summary_word_budget: 250
memory_digest_token_budget: 1200
log_tail_lines_on_error: 50
raw_log_policy: path-only
agentmemory: optional
created_utc: "2026-04-28T09:00:00Z"
tasks:
- id: T1
agent: codex
slug: extract-interfaces
description: "Define abstract base classes in src/auth/interfaces.py"
depends_on: []
files_in_scope:
- "src/auth/interfaces.py"
files_out_of_scope:
- "src/auth/legacy.py"
- "tests/**"
success_criteria:
- "src/auth/interfaces.py exists and defines AuthProvider ABC"
- "no other source files modified"
- id: T2
agent: codex
slug: refactor-providers
description: "Move existing provider classes to inherit from new ABC"
depends_on: [T1]
files_in_scope:
- "src/auth/providers/*.py"
success_criteria:
- "pytest tests/auth/test_providers.py passes"
- "no imports of src.auth.legacy from other modules"
- id: T3
agent: claude-cheap
model: haiku
slug: doc-coverage-inventory
description: "List every public symbol in src/auth and whether it has a docstring mentioning the legacy class (mechanical inventory; the JUDGMENT of coverage adequacy stays in T4)"
depends_on: [T1, T2]
success_criteria:
- "a table of every public symbol in src/auth with has_docstring yes/no"
- "rows flagged where the docstring mentions the legacy class"
- id: T4
agent: claude
slug: design-review
description: "Read T1-T3 outputs, verify the architecture choice survives the implementation"
depends_on: [T1, T2, T3]
success_criteria:
- "explicit YES/NO verdict + rationale in chat"
```
### 6. Write per-agent task files
Each lane has **its own task file convention**. Don't use a single
template for all โ each executor expects its own shape.
**Every task brief MUST include a pre-task scope confirmation block
(W1, prevents drift)**:
```markdown
## Pre-task scope confirmation (REQUIRED โ your first action)
Before any file edit, echo back the scope you understand:
Confirmed scope: will touch
- <file1>
- <file2>
Will NOT touch
- <file3>
- any file not listed under "Files in scope" above
- any meta-documentation table (F11)
- any unrequested metadata line (F12)
If your understanding doesn't match the brief's "Files in scope"
section, STOP and ask for clarification before editing anything.
```
This block is verified post-task by `agent-acceptance-gate` ยง6.6
(scope diff check via `git diff --name-only`).
#### 6a. Codex task files (`agent: codex`)
Path: `.ai/codex_task_<NNN>_<slug>.md`. `<NNN>` is the zero-padded
`round` (`001` for round 1). Format follows `codex-delegate`'s
"Supervisor Workflow" section:
```markdown
# Task: <description>
## Context
- Repo: <absolute path>
- Plan: .coord/plan.yml (round <N>, task <T-id>)
- Read these files first:
- <files_in_scope items + relevant references>
- Only modify (files_in_scope):
- <files_in_scope items>
- .ai/codex_result_<NNN>_<slug>.md โ REQUIRED: the result-summary file
- Do NOT touch (files_out_of_scope):
- <files_out_of_scope items>
- Depends on outputs of: <list T-ids + their result paths>
## Goal
<task.description, expanded with concrete deliverable>
## Constraints
- Follow adjacent code style.
- Do not make architectural changes beyond the scope.
- Do not edit files outside the allowed list.
## Acceptance
- Required tests: <test command from success_criteria>
- Required result summary: write a concise summary to
Before writing the task body, classify the task by **output shape**:
| Task shape | Format guidance to include in brief |
|---|---|
| **Pedagogical** (curriculum, tutorial, explainer) | "Prefer prose. A table is justified ONLY if (a) data is genuinely comparative (โฅ3 attributes per row) AND (b) reader will use it as decision tool, not inventory. 'Catalog of N variants' is anti-pattern โ replace with prose covering 2-3 axes + `<details>` for long tail." |
| **Reference** (API docs, schema definitions) | "Tables OK for structured data. Each table should answer one specific question." |
| **Catalog** (project listings, comparisons) | "Tables OK but include: (a) โค 10 entries in primary table; (b) `<details>` collapsible for long tail; (c) live `gh api` verification step for stars/license/pushed_at โ required in `result.md`." |
| **Migration / mechanical edit** (rename, replace pattern) | "No tables. Concrete file list + diff summary." |
| **Translation / mirror-sync** | "Maintain source structure VERBATIM. No new tables, no removed tables, no merged tables. Column counts must match per-table across locales. (F2 incident)" |
This block should appear in `## Format guidance` section of every
task brief. Skipping it is the F6 root cause.
**Also include these 2 explicit prohibitions in every brief that
applies a sweep rule across files (prevents F11, F12)**:
```markdown
## Drift guards โ DO NOT (F11, F12 from docs/observed-failure-modes.md)
### F11. Skip meta-documentation tables
Do NOT replace term X with term Y in any row that literally documents
If the user reassigns a task to a different agent **after** plan.yml
and task files were already written (e.g., "actually, T2 should be
claude-cheap, not codex"):
1. **Edit the agent assignment in `.coord/plan.yml`** for that
single task. Don't bulk-replace โ surgical edit only. Bulk
`sed` replacements typically over-match and rewrite assignments
you wanted to keep.
2. **Delete the obsolete task file** (e.g., the old
`.ai/codex_task_<NNN>_<slug>.md` if T2 was codex and is now
claude-cheap). Lingering obsolete files confuse the reconciler โ it
may pick them up and report on a task that didn't actually run.
3. **Write the new task file** in the new agent's format (per step
6a / 6c-2). Slug stays the same; only the agent prefix changes.
4. **If dependents already ran** (e.g., T3 ran depending on T2's
old codex output): note in the round's `.coord/memory.yml`
that T3's output was based on a now-stale T2; flag for re-review
in the reconciliation report.
Re-planning mid-round is normal. The schema supports it; just be
explicit about what changed instead of letting orphan files
accumulate.
## What NOT to do
- **Don't run any agent.** This skill stops at writing files.
- **Don't fabricate `success_criteria`.** If the user hasn't told
you what success looks like and you can't infer it from context,
ask before writing the plan.
- **Don't create unbounded task packets.** Use `context_policy` and
keep each task file to the critical files, constraints, and result
contract. Link paths instead of pasting logs or long analysis.
- **Don't classify everything as Codex.** Real multi-agent runs
benefit from heterogeneity. If your plan has 5 tasks all routed
to Codex, reconsider whether the goal needs a multi-agent split
or just one big Codex run.
- **Don't put architecture / design decisions in `agent: codex`
tasks.** Those go to Claude (or to `agent-debate` if
consequential).
- **Don't number `<NNN>` independently per task.** It matches
`round`. All tasks in round 1 use `001` in their filename. The
task `slug` distinguishes them.
## Heuristics for the hardest case (when to split at all)
If you find yourself writing a 1-task plan, you're using the wrong
skill โ invoke `codex-delegate` or `claude` directly. The splitter
earns its keep when:
- The goal has both judgment-heavy and mechanical components.
- Multiple files / domains / stages need work in parallel.
- A long-context read + a code edit are both required.
- An adversarial review on the result would be valuable (then
consider also queueing `agent-debate` after).
## Subagent review (keep main session lean)
**When**: โฅ 4 task files written in one round, OR โฅ 2 agents will run
in parallel.
**Why**: The main session that just wrote `plan.yml` + N task files
already holds the entire plan in context. Asking it to also verify
slug/agent/path consistency across all task files doubles the context
cost. Delegate the verification to a subagent that returns only the
verdict.
**Pattern** (Claude Code's Task tool, or equivalent subagent harness):
```
Spawn `code-reviewer` subagent with this brief:
- Read .coord/plan.yml + every .ai/{codex,claude}_task_<NNN>_*.md
generated this round (the gemini glob applies only when reconciling
a historical pre-deprecation round)
- Verify: (a) each plan.yml task has a matching task file at correct
path; (b) slugs in filenames match plan.yml task.slug exactly;
(c) agent assignment matches; (d) no orphan task files from prior
rounds; (e) each task file's "Output file(s)" section references
the required result-summary path
- Return: PASS / FAIL + โค 200-word verdict + list of any drifted
slug/agent/path mismatches
Main session reads only the verdict; never re-reads the task files.
```
If subagent reports FAIL, run step 8 (re-plan) on the flagged tasks
before invoking delegates.
## Output to user (final message format)
```
[agent-task-splitter]
Plan: .coord/plan.yml (round 1, 4 tasks)
Routing: 2ร codex, 1ร claude-cheap, 1ร claude
DAG: T1 โ [T2, T3] โ T4
Task files ready under .ai/
Run order (respecting dependencies):
1. codex T1 (no deps)
2. codex T2 + claude-cheap T3 (parallel after T1)
3. claude T4 (after T2 + T3)
After all 3 external tasks finish:
invoke agent-output-reconciler
```
## Commit Boundary
Every agent boundary is a commit boundary (see global rule:
~/.claude/CLAUDE.md โ "Commit Discipline for Multi-Agent Work"). This
makes multi-agent work auditable (commit log = agent log) and enables
surgical rollback via `git revert <hash>` of just one agent's commit.
**Specific to this skill**: after the splitter writes `.coord/plan.yml` and per-agent `.ai/<agent>_task_<NNN>_<slug>.md` files, commit them as a single 'plan commit' before any agent begins execution. This gives every downstream agent's commit a clean parent to attribute work against.
