Multi-Agent Orchestration skill for Claude Code

A multi-agent design is justified when the work splits into independent pieces whose reading would overflow one context or whose parallelism cuts wall-clock time, and the extra tokens (often 3-15x a single agent) are worth it. Done well, each worker gets a self-contained brief, returns a compact structured result, and the orchestrator owns synthesis, budgets, and failure handling.

Ground rules

• Default to one agent with good tools. Add agents only when you can name the bottleneck they remove: context overflow, parallel wall-clock, or a genuinely different role (e.g. independent reviewer).
• Workers do not share the orchestrator’s context. Everything a worker needs goes in its brief; assume it knows nothing else.
• Workers return distilled results (findings, file paths, evidence), not transcripts.
• Write-heavy tasks that touch the same files or state do not parallelize safely. Split by ownership or serialize.
• Put hard limits on fan-out, concurrency, per-worker tokens, and total spend.

Should this be multi-agent?

Signal	Verdict
Task is “research N independent topics / sources / files, then synthesize”	Good fit: orchestrator + parallel workers
One loop would read far more than fits in context	Good fit: workers read, return summaries
You need an independent check (reviewer that did not write the code)	Good fit: separate reviewer agent
Steps are sequential and each depends on the last	Poor fit: one agent or a workflow
Many agents editing the same codebase or document	Poor fit: conflicts and inconsistency
Low-value, latency-sensitive request	Poor fit: cost and latency dominate
You want “a team of personas” chatting	Poor fit: role-play adds tokens, not capability

Patterns

Pattern	Shape	Use when
Orchestrator-worker	Lead plans, spawns workers with briefs, synthesizes	Breadth-first research, multi-file analysis
Parallel map-reduce	Code fans out the same prompt over N items, then one reduce call	Items are uniform (documents, records); no planning needed
Pipeline	Agent A output -> Agent B input, fixed order	Distinct stages with different tools or models (extract -> verify -> draft)
Generator-critic	One produces, another evaluates against a rubric, loop bounded	Quality bar is checkable; cap at 2-3 rounds
Router	Cheap classifier sends the request to one specialist	Distinct domains with different tools/prompts

Prefer code-orchestrated fan-out (map-reduce) over model-orchestrated when the split is known in advance; it is cheaper, deterministic, and easier to test.

Workflow

- [ ] 1. Confirm the fit (table above) and estimate cost vs. single agent
- [ ] 2. Define the decomposition rule and max fan-out
- [ ] 3. Write the worker brief template and result schema
- [ ] 4. Implement bounded parallel execution
- [ ] 5. Implement synthesis with conflict handling
- [ ] 6. Add failure handling, budgets, and tracing
- [ ] 7. Evaluate against the single-agent baseline

2. Decomposition

• Scale effort to the task: simple fact-finding, 1 agent; comparisons, 2-4 workers; broad research, 5-10 workers. Put this rule in the orchestrator’s prompt explicitly, or it will over-spawn.
• Split on boundaries that minimize overlap: distinct sources, directories, time ranges, or sub-questions. Tell each worker what the others cover so it does not drift into their area.

3. Worker brief template

<objective>One sentence: what to find or produce.</objective>
<context>Why this matters and what the overall task is (2-3 sentences).</context>
<scope>
In scope: ...
Out of scope (covered by other workers): ...
</scope>
<tools_and_sources>Which tools to use, preferred sources, things to avoid.</tools_and_sources>
<budget>At most N tool calls; stop early when the objective is met.</budget>
<output_format>
Return JSON matching the schema: findings[] with claim, evidence, source, confidence;
open_questions[]. No narrative.
</output_format>

Vague briefs (“research the market”) produce duplicated, shallow work. Every brief needs objective, boundaries, output format, and budget.

4. Bounded parallel execution (code-orchestrated)

import asyncio, json
from anthropic import AsyncAnthropic

client = AsyncAnthropic(max_retries=4)
SEM = asyncio.Semaphore(8)            # concurrency cap; size to your rate limits

async def run_worker(brief: str) -> dict:
    async with SEM:
        resp = await client.messages.parse(
            model="claude-haiku-5-5",         # cheap worker for reading-heavy subtasks
            max_tokens=4000,
            system=WORKER_SYSTEM,
            messages=[{"role": "user", "content": brief}],
            output_format=WorkerResult,        # Pydantic model: findings, open_questions
        )
        return {"ok": True, "result": resp.parsed_output, "usage": resp.usage}

async def orchestrate(briefs: list[str]) -> list[dict]:
    tasks = [asyncio.wait_for(run_worker(b), timeout=180) for b in briefs[:MAX_FANOUT]]
    outs = await asyncio.gather(*tasks, return_exceptions=True)
    return [o if isinstance(o, dict) else {"ok": False, "error": repr(o)} for o in outs]

Model assignment:

Role	Default model
Orchestrator / planner / synthesizer	Strongest model you can afford (claude-opus-5-5)
Reading and extraction workers	Cheap, fast model (claude-haiku-5-5), or claude-sonnet-5-5 when judgment is needed
Critic / verifier	At least as strong as the generator

Measure before adopting a cascade: a single strong model at lower effort sometimes matches it at lower total cost, and each distinct model has its own prompt cache.

5. Synthesis

• Give the synthesizer all worker results plus the original task; ask it to merge duplicates, flag contradictions with both sources, and note gaps.
• Keep provenance: every claim in the final output links to the worker finding and source.
• If gaps matter, allow one bounded follow-up round of targeted workers, not open-ended recursion.

6. Failure handling and budgets

• A failed or timed-out worker is reported to the synthesizer as missing coverage, not silently dropped.
• Retry a failed worker once; then continue without it.
• Track tokens per worker and in total; abort spawning when the total budget is hit.
• Trace each worker as a child span with its brief, result, tokens, and latency (see llm-observability). Debugging multi-agent runs without traces is guesswork.
• Make the orchestration resumable for long jobs: persist completed worker results so a crash does not re-run them.

7. Evaluate

Run the same 20-50 tasks through the single-agent baseline and the multi-agent design. Compare quality (graded with llm-evals), total tokens, cost, and wall-clock. Keep the multi-agent version only if it wins on quality or latency by enough to pay for itself.

Gotchas

• Over-spawning: models create 20 workers for a simple question unless the scaling rule is explicit.
• Telephone effect: results passed through several agents lose detail. Workers can write full artifacts to storage and return a reference plus summary.
• Parallel writers to shared state (same repo, same doc, same DB rows) produce conflicts; give each worker exclusive ownership (separate files, git worktrees, or records).
• Rate limits: fan-out of 50 concurrent calls triggers 429 storms; cap concurrency and use SDK retries with backoff.
• Workers inheriting the orchestrator’s full conversation multiplies cost and confuses scope. Pass a brief, not the history.
• Hosted options exist (the Claude Agent SDK’s subagents, server-managed agent sessions with delegation). They change where the loop runs, not the design rules above.

Output contract

**Pattern:** <orchestrator-worker | map-reduce | pipeline | generator-critic | router>
**Why multi-agent:** <bottleneck removed>; single-agent baseline <score, cost, time>
**Fan-out:** max <n> workers, concurrency <c>, models <orchestrator/worker>
**Budgets:** <tokens or $ per run>, worker timeout <s>, retries <n>
**Result:** quality <x> vs. baseline <y>; cost <a> vs. <b>; wall-clock <t1> vs. <t2>