multi-agent-orchestration
Guides deciding when and how to split a task across multiple cooperating LLM agents (supervisor/worker, pipeline, or debate patterns) instead of one agent with many tools. Use when a user asks to "design a multi-agent system," "should this be one agent or several," "orchestrate sub-agents," fix agents that duplicate work or talk past each other, or is deciding how a supervisor agent should delegate to and validate specialist agents.
selvarajmurugesan90 · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add selvarajmurugesan90/ops-engineering-skills --skill multi-agent-orchestrationAbout this skill
name: multi-agent-orchestration description: > Guides deciding when and how to split a task across multiple cooperating LLM agents (supervisor/worker, pipeline, or debate patterns) instead of one agent with many tools. Use when a user asks to "design a multi-agent system," "should this be one agent or several," "orchestrate sub-agents," fix agents that duplicate work or talk past each other, or is deciding how a supervisor agent should delegate to and validate specialist agents. license: Apache-2.0 compatibility: "Claude Code, GitHub Copilot, OpenAI Codex, Cursor, Gemini CLI" metadata: domain: ai-agent maturity: stable
Multi-Agent Orchestration
Purpose
Splitting a task across multiple agents can reduce per-agent context load, allow specialization (a narrower system prompt and tool set per role), and enable parallelism — but it also multiplies the surface area for coordination failures: duplicated work, agents that silently disagree, lost context at hand-off boundaries, and cost/latency from redundant model calls. Multi-agent orchestration is not automatically better than a single well-designed agent; it is a specific tool for specific shapes of problem. This skill covers the common orchestration topologies (supervisor/worker, pipeline, debate/parallel-with-aggregation), when each is justified over a single agent, and how to keep hand-offs between agents reliable.
When to use
- A single agent's context or tool set has grown large enough that it shows role confusion or degraded performance on any one sub-task (a concrete threshold to check, established in agent-architecture-design, before reaching for multi-agent as a fix).
- A task naturally decomposes into independent workstreams that can run in parallel (e.g. researching three unrelated topics before synthesizing).
- A task benefits from specialist framing — a code-review sub-agent with a narrow reviewer persona genuinely produces better reviews than one generalist agent asked to "also review code" among ten other jobs.
- You need a distinct verification/critic role separate from the agent that produced the output, to catch errors the producing agent is blind to.
- Debugging duplicated work, contradictory outputs, or lost context between cooperating agents in an existing multi-agent system.
Prerequisites & environment
- A working single-agent implementation first — multi-agent orchestration should be an evolution from a scoped single agent, not a starting design, since most of its coordination problems only become visible once you've seen where a single agent actually strains.
- An orchestration mechanism: a supervisor process/agent that dispatches to sub-agents and collects results, whether hand-rolled or via a framework/runtime.
- A shared understanding across the team of what state, if any, is common vs. private to each sub-agent (see step 3 below) — undocumented shared state is the most common source of multi-agent bugs.
- Cost/latency budget awareness: N agents each making LLM calls costs roughly N× a single agent's calls for the same step, before accounting for coordination overhead (see llm-cost-and-latency-optimization).
Step-by-step guidance
-
Justify the split with a concrete symptom, not intuition. Before introducing a second agent, write down what specifically breaks with one agent: context window pressure, measurable role confusion in evaluation results (see agent-evaluation-and-guardrails), or a genuine need for parallel independent work. "It felt cleaner to split it" is not sufficient justification given the added coordination cost.
-
Choose a topology that matches the task's dependency structure:
- Supervisor/worker: one supervisor agent plans and delegates discrete sub-tasks to worker agents (each with a narrow prompt and tool set), then integrates results. Best when sub-tasks are specialized but the overall task needs central coordination.
- Pipeline: agents run in a fixed sequence, each consuming the
prior stage's output (e.g.
researcher -> writer -> fact_checker). Best when the task has a natural linear dependency chain. - Parallel + aggregation (fan-out/fan-in): independent agents work on genuinely independent sub-parts simultaneously, then a final step merges results. Best for independent workstreams (e.g. summarizing three unrelated documents) where order doesn't matter.
- Critic/debate: a second agent explicitly reviews or challenges the first agent's output before it's finalized. Best when catching a specific class of error (factual, safety, style) matters more than speed.
-
Define the hand-off contract between agents explicitly, as a structured schema, not free-form prose passed between prompts:
{ "from_agent": "researcher", "to_agent": "writer", "task_id": "task-8842", "findings": [ { "claim": "...", "source": "doc-42", "confidence": "high" } ], "open_questions": ["..."] }Free-form hand-offs ("here's what I found: ...") are the single biggest source of lost or misinterpreted context between agents.
-
Give each sub-agent the narrowest system prompt and tool set that its role needs — this is the actual payoff of splitting; a worker agent with a 10-line role-specific prompt and 3 tools will outperform the same role embedded as one section of a 40-tool generalist's prompt.
-
Make the supervisor responsible for validating hand-offs, not just routing them — check that a worker's output matches the expected schema and addresses the delegated sub-task before passing it downstream or integrating it, rather than assuming compliance.
def supervisor_step(task):