renatoschust-dot/gamai-skills/agents-swarm-orchestration
Claude Code and agent skill by renatoschust-dot/gamai-skills
- community
Checking that the SKILL.md file is still in the repository.
Coordinates multi-agent execution across subagents, teams, and workflows. Use when planning dependency-aware fan-out, verifier passes, runtime selection, or Loop Engineering.
Install
npx vskill@latest install renatoschust-dot/gamai-skills/agents-swarm-orchestrationSKILL.md
The same SKILL.md was published earlier as renatoschust-dot/gamai-skills/agents-swarm-orchestration.
Swarm Orchestration
Advanced execution layer for multi-worker runs after agent or team selection.
Coordinate multiple workers without polluting the main thread. Use this skill after agents-subagents has already selected the right agent, member, team, or debate pattern. This skill is for choosing the orchestration surface, freezing task ownership before fan-out, and requiring structured outputs that the lead agent can validate and merge safely.
Terminology (Aug 2026)
"Swarm" is community vocabulary — it appears nowhere in Anthropic documentation. Use the official primitive names when writing configs, prompts, or docs; keep "swarm" only as informal shorthand for the whole category.
| Informal | Official primitive | Status (Aug 2026) | |
|---|---|---|---|
| "swarm of subagents" | Subagents | GA. Background behavior is mode-dependent; background: true forces background but false is not a documented foreground pin. Recursive spawn currently defaults to three layers below the main session | |
| "swarm with peer chat" | Agent teams | Experimental, env-gated CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Behavior churns weekly — re-verify before relying | |
| "scripted swarm" | Dynamic workflows | Shipped 2026-05. JS in .claude/workflows/; ≤1000 agents/run, 16 concurrent. The repeatable-orchestration artifact | |
| "swarm across terminals" | Cross-session messaging | Aug 2026, macOS/Linux. Sessions message each other without a team — lighter than teams for passing findings |
Quick Reference
| Situation | Default pattern | Why | |
|---|---|---|---|
| 1-2 tasks or shared-file edits | Stay in the main conversation | Parallelism adds coordination overhead without payoff | |
| Focused worker that only needs to report back | Claude Code subagent or Codex worker | Isolated context, simple coordination | |
| Workers must talk to each other | Claude Code agent team | Shared task list plus direct messaging | |
| Read-heavy scans, tests, triage, summarization | Parallel workers | Keeps noisy intermediate output off the lead thread | |
| One coordinator should retain user ownership | Manager / agents-as-tools | Lead keeps control of decisions and final answer | |
| Specialist should take over the conversation | Handoff | Ownership moves to the specialist agent | |
| Work of unknown extent — discovery is the task | Loop until K empty rounds | A fixed task list cannot be enumerated up front | |
| Loop Engineering: recurring discovery or evaluation | Loop-until-dry or budget-bounded loop | Define convergence, termination, and state checkpoints | |
| Many items, known stages, high intermediate volume | Scripted workflow (Claude Code) | Script holds control flow; lead context holds only the result |
Navigation
- references/loop-orchestration.md - Bounded iteration vs retry, loop-until-dry, convergence detection, termination predicates, dedup-target rule
- ../ai-coding-agents-tasks/references/loop-and-graph-runtime-surfaces.md - Loop Engineering and Graph Engineering runtime comparison: task queues, cyclic graphs, and workflows
- references/scripted-workflows.md - Script-held deterministic control flow (Claude Code Workflows):
agent/parallel/pipeline, barrier-vs-pipeline, resume and caching - references/platform-patterns.md - Platform guidance for Claude Code subagents, Codex subagents, Codex multi-agents, and OpenAI Agents SDK
- references/output-contracts.md - Task schema, worker report schema, and merge contract
- references/operational-guardrails.md - Safety, stop conditions, observability, and verification gates
- references/cost-discipline.md - Fan-out cost patterns, session lifecycle, loops/schedules audit, orchestration-layer config
- references/orchestration-maintenance-runbook.md - How to audit, maintain, and refresh swarm discipline over time
- references/runtime-smoke-tests.md - 3 shell-runnable checks for wave dispatch, per-worker budget breach, and wave-boundary checkpoints
- references/execution-surfaces.md - Single thread, worker fan-out, agent team, manager, and handoff selection
- references/noninteractive-and-blueprints.md - CI-safe dispatch patterns and deterministic-plus-agentic blueprint flows
- references/recipe-wave-dispatch.md - Self-contained 3-worker shell example: copy, paste, run, verify
- references/typical-scenarios.md - Scenario library: common jobs mapped to surface, pattern, worker shape, and the trap to avoid
agents-subagents- Subagent design, tool scoping, and interruption recovery- ../agents-hooks/SKILL.md - Hook guardrails and verification automation
- ../agents-mcp/SKILL.md - MCP server scoping for workers
- ../agents-skills/SKILL.md - Skill packaging for worker preloads
- ../agents-memory/SKILL.md - Project memory for shared conventions
- ../ai-coding-agents-permissions/SKILL.md - Approval routing, allow or ask modes, and worker permission handoff
- ../ai-coding-agents-tasks/SKILL.md - Background task runtimes, teammate queues, and task ownership
- ../dev-workflow-planning/SKILL.md - Create the plan before fan-out
- ../ai-agents/references/autonomous-loop-patterns.md - Shape C autonomous loops: PRD-driven drivers, circuit breakers, drift detection (framework-neutral)
- ../ai-agents/references/context-graph-patterns.md - Graph-structured agent state: node/edge schema, traversal, conflict resolution
- data/sources.json - Curated official docs, research, and secondary references
Maintainer note: eight URLs here are intentionally duplicated from../agents-subagents/data/sources.json(Claude Code subagents, Agent Teams, Codex Multi-Agents, Codex Subagents, both OpenAI Agents SDK pages, OpenAI prompt-caching guide, Karpathy coding notes). Each skill frames those sources for a different reader. When a URL rotates, update both files in the same commit.
When To Use / Not To Use
| Use | Do Not Use | |
|---|---|---|
agents-subagents already chose the team; now needs execution planning | Still deciding which agent, team, or debate mode fits | |
| 3+ bounded tasks with clear ownership or dependencies | Tasks share the same file or unresolved interface | |
| Requirements, decisions, synthesis must stay in one lead context | Main blocker is product ambiguity, not execution bandwidth | |
| Exploration, tests, logs, or review can run in parallel | Workers would need the same context and make the same decisions | |
| Loop Engineering needs a bounded multi-pass orchestration contract | One pass or a simple queue already meets the goal | |
| Verification must be explicit, not implied by worker confidence | Work is small enough that orchestration cost exceeds execution cost |
Relationship To Agents-Subagents
agents-subagents is the entry point. It selects the mode and prepares the first launch prompt. This skill takes over when the plan needs multi-wave execution, worker dependencies, verifier passes, or merge/conflict control.
Operating Principles
- Lead owns requirements, decisions, approvals, and final synthesis — not execution.
- Default to read-heavy parallelism; parallel writes are higher-risk.
- Freeze shared interfaces before dispatching edit-capable workers.
- Give every worker exclusive
owned_filesand explicitdo_not_touchboundaries. - Pass distilled dependency outputs, not raw logs or long transcripts.
- Require structured worker reports — the lead validates and merges deterministically.
- Re-plan when conflict resolution costs more than the fan-out saved.
- Fresh context per worker: each worker brief contains only its task, plan section, file ownership, and interface contracts — not the lead's full history. Prevents context rot; gives each worker a full window.
- State in files: task graph, progress, decisions, and dependency outputs live in structured files (frontmatter MD / JSON / YAML). Any new lead session resumes by reading files, not memory.
- Checkpoint long runs: snapshot task state, reports, and decisions to
checkpoints/at each wave boundary. - Budget per worker: explicit token/time/tool caps at dispatch. Budget-conservation invariant: child budgets are strict subsets of the parent's remaining budget. Workers that breach their budget stop and escalate — they do not continue. (Ye & Tan, Agent Contracts: A Formal Framework for Resource-Bounded Autonomous AI Systems, arXiv:2601.08815, 2026)
- Telemetry per worker: assign a run id or span id; log inputs, outputs, status, tokens, and duration to one structured location.
- Durable approval channels: route approvals through mailbox/poller with request IDs, not ephemeral callbacks.
- Minimum toolset per worker: use
tools,disallowedTools, andskillsfields to give each worker only what it needs. - Memory opt-in: prefer clean-context workers + file-backed checkpoints. Enable
memoryonly when the role genuinely benefits from cross-run priors; never default it for verifiers or reviewers. Prefer file tools over schema-constrained memory APIs. (Lance Martin, 2026-04-24; `../ai-context-layer/references/filesystem-as-memory.md`)
For context rotation and state handoff patterns, see `../ai-agents/references/context-rotation-and-state.md`.
Explicit Fan-Out Is The Durable Default
Claude Opus 4.7 (GA 2026-04-16) shipped a lasting behavior change: it spawns fewer subagents by default than 4.6, favoring single-response completion over implicit parallelism. Fan-out workflows that previously worked without being asked — read-heavy scans, multi-file refactors, review waves, cross-repo audits — now silently serialize unless the lead is told to fan out explicitly. Opus 4.8 (current as of this writing) inherits the same conservative default; treat "assume no auto-parallelism" as the standing assumption for whatever frontier model is current, and re-verify against release notes each time the lead model changes.
Anthropic's source guidance is to give the model explicit fan-out instructions; it does not prescribe where the instruction must live. Our repo convention is to install the canonical phrasing once in AGENTS.md / CLAUDE.md (not duplicated per launch prompt):
Spawn multiple subagents in the same turn when fanning out across items or reading multiple files. Do not spawn a subagent for work you can complete in a single response.
Full guidance and source links live in agents-subagents. Judgment call for the lead: after any model swap, run one throwaway fan-out task and watch whether it parallelizes on its own — cheaper than discovering silent serialization mid-migration.
Named Patterns
Name the pattern explicitly when proposing a design. Full detail: ../agents-subagents/references/harness-patterns.md.
This is the start of the file. Read the full SKILL.md on GitHub.
Security
- Security scanPassed, 95 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/agents-swarm-orchestration/SKILL.md
Popularity
- 7-day trend score
- 5
Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/renatoschust-dot/gamai-skills/agents-swarm-orchestration)