orchestrating-swarms Skill

Use swarms when the work has real parallelism, specialist boundaries, or dependency staging. If one agent can finish faster than the coordination overhead, stay single-threaded.

When to use

• Parallel research, review, or implementation tracks.
• Pipeline work where one stage unlocks another.
• Large tasks that benefit from specialist prompts and explicit handoffs.
• Situations where a leader must merge findings from multiple workers.

Workflow

1. Decide whether you need a swarm. Prefer one agent for linear work, tiny diffs, or tasks with one obvious path.
2. Break the job into independent units with owners, dependencies, and a concrete finish condition for each unit.
3. Choose the right worker shape: short-lived subagents for one-off work, persistent teammates only when shared coordination is necessary.
4. Give every worker full context: goal, scope, constraints, expected output, and what not to touch.
5. Track progress, unblock dependencies, merge results, verify the combined outcome, then shut the swarm down cleanly.

Operating guide

Subagent vs teammate

• Use a normal Task/subagent when you want a focused result returned directly.
• Use a teammate only when the worker needs a shared queue, persistent inbox messaging, or multi-step coordination.
• Keep the team small. Extra workers are justified only when they remove wall-clock time or increase specialist quality.

Task design

• Write tasks as outcomes, not vague topics.
• Keep scopes non-overlapping unless the assignment is an explicit cross-check.
• Prefer DAG-style dependencies over ad hoc sequencing.
• State what evidence counts as done: files changed, tests run, findings delivered, screenshots captured, or open questions listed.

Message contract

Have workers report in a terse, machine-checkable shape:

• status: ready | blocked | done
• scope: what they owned
• evidence: commands, files, screenshots, or metrics
• handoff: what the next worker or leader must do
• risks: unresolved concerns

Leader responsibilities

• Keep the canonical task list and dependency map.
• Resolve blockers instead of letting workers stall silently.
• Merge duplicate findings and remove contradictory advice.
• Re-run shared verification after integrating worker output.
• Shutdown teammates after their work is accepted.

Output

• Swarm plan: workers, scopes, dependencies, and completion signals.
• Progress log: blocked vs active vs done.
• Final synthesis: merged findings, verification evidence, and remaining risks.

Guardrails

• Do not use a swarm as a substitute for thinking through the decomposition.
• Do not create overlapping workers without saying why overlap is useful.
• Do not dispatch named specialists without their full template or operating contract.
• Do not accept worker claims without evidence you can trace.
• Always close the loop with integrated verification, not just per-worker success.