⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
choosing-swarm-patterns
Use when coordinating multiple AI agents with Agent Relay's workflow engine and need to pick the right orchestration pattern - covers the 10 core patterns (fan-out, pipeline, hub-spoke, consensus, mesh, handoff, cascade, dag, debate, hierarchical) plus 14 specialized ones, with decision framework and accurate SDK/YAML examples.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
Infrastructure for coding agents
Tired of copy/pasting from Claude Code into Slack so your coworker can paste it into their agent?
Ever put an important rule in a skill or AGENTS.md, only for the agent to completely ignore it?
You and your teammates agents ever build the same thing? Wondered whether your coworker's agent made that change intentionally? How many times have you typed "babysit this PR until CI passes"?
Agent Relay is an open-source toolkit for problems like these. It gives engineering teams infrastructure for running coding agents together without replacing the agents and tools they already use.
Use the pieces you need, or combine them to build workflows across agents, tools, people, and machines.
Messaging
Claude/Codex/etc can talk directly through shared channels, threads, DMs, files, search, and real-time events. Agents can run on different machines and still coordinate in the same workspace.
Integrations
GitHub, Linear, Notion, Slack, and other tools are exposed as a virtual filesystem. Agents use ls, cat, grep, and ordinary file writes to work with them.
Shared Sessions
Capture coding agent sessions so your team and their agents can search previous work, decisions, and context.
Agents can search team history through the Shared Sessions plugin, or connect its MCP with agent-relay mcp --sessions-only after Cloud login.
How we capture sessions How we capture decisions
Flows
Turn instructions you hope an agent follows into workflows you can enforce.
Define multi-step workflows in TypeScript with deterministic checks, required steps, and human gates. Put the rules that matter in code instead of relying on a skill or prompt to be remembered and followed.
Learn how write a flow (or lets be honest, show your agent how)
Getting Started
In a project folder, with Node.js 22 or newer:
npx -y agent-relay@next init
Open Claude Code or Codex there, then open a second session in another terminal. Each one joins Relay by itself. Run npx -y agent-relay@next agent list to see their names, then ask one agent to "DM <name> over Agent Relay".
With teammates: one person runs npx -y agent-relay@next init --hosted and shares the init --key line it prints.
More in the getting started guide.
Upgrade: the paid Agent Relay desktop app adds shared sessions and communication across more of your agents.
Self Hosting
Agent Relay has self hosting options for each primitive; start with the self-hosting guide. We're happy to help you set up the whole system on your environment, just reach out to our team hi(at)agentrelay.com and we'll walk you through it.
License
Apache-2.0 - Copyright 2026 Agent Workforce Incorporated
Links: Website · Documentation · Docs (Markdown) · Discord
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
.agents/skills/choosing-swarm-patterns/SKILL.md7.9 KBupstream ↗
--- name: choosing-swarm-patterns description: Use when coordinating multiple AI agents with Agent Relay's workflow engine and need to pick the right orchestration pattern - covers the 10 core patterns (fan-out, pipeline, hub-spoke, consensus, mesh, handoff, cascade, dag, debate, hierarchical) plus 14 specialized ones, with decision framework and accurate SDK/YAML examples. --- ### Overview ### Overview The Agent Relay SDK (`@agent-relay/sdk`) supports 24 swarm patterns via a single `swarm.pattern` field. Patterns are configured declaratively in YAML — there are no standalone `fanOut(...)` / `hubAndSpoke(...)` helpers. Pick the simplest pattern that solves the problem; add complexity only when the system proves it's insufficient. ### Run a pattern #### TypeScript SDK runner ```ts import { runWorkflow } from '@agent-relay/sdk/workflows'; const run = await runWorkflow('workflows/feature-dev.yaml', { vars: { task: 'Add OAuth login' }, }); ``` ### Quick Decision Framework ```text Is the task independent per agent? YES → fan-out (parallel workers, hub collects) Does each step need the previous step's output? YES → Is it strictly linear? YES → pipeline NO → dag (parallel where possible, `dependsOn` edges) Does a coordinator need to stay alive and adapt? YES → hub-spoke (single-level hub + workers) hierarchical (structurally identical in current impl; use for naming/intent) Is the task about making a decision? YES → Do agents need to argue opposing sides? YES → debate (adversarial, full mesh) NO → consensus (cooperative, full mesh + coordination.consensusStrategy) Does the right specialist emerge during processing? YES → handoff (sequential chain, one active at a time) Do all agents need to freely collaborate? YES → mesh (full peer-to-peer edges) Is cost the primary concern? YES → cascade (chain of increasingly capable agents; each step's prompt decides whether to pass through or redo the prior output) ``` ### Pattern Reference (Core 10) | # | Pattern | Topology (actual edges) | Best For | | --- | ---------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | | 1 | **fan-out** | Hub broadcasts to N workers; workers reply to hub only | Independent subtasks (reviews, research, tests) | | 2 | **pipeline** | Linear chain (`agent_i` → `agent_{i+1}`) | Ordered stages (design → implement → test) | | 3 | **hub-spoke** | Hub ↔ spokes (bidirectional); no spoke-to-spoke | Dynamic coordination, lead reviews/adjusts | | 4 | **consensus** | Full mesh; decision via `coordination.consensusStrategy` | Architecture decisions, approval gates | | 5 | **mesh** | Full mesh (every agent ↔ every other) | Brainstorming, collaborative debugging | | 6 | **handoff** | Chain; passes control forward | Triage, specialist routing | | 7 | **cascade** | Chain of `dependsOn` steps; all run on success, downstream skipped on upstream failure (no built-in "fall through") | Cost optimization: cheap first, each step's prompt passes through or redoes | | 8 | **dag** | Edges from step `dependsOn` | Mixed dependencies, parallel where possible | | 9 | **debate** | Full mesh (same topology as mesh; roles drive behavior) | Rigorous adversarial examination | | 10 | **hierarchical** | Hub + subordinates (single-level in current impl) | Large teams; semantic distinction from hub-spoke | > **Heads up:** `hierarchical` resolves to the same edge structure as `hub-spoke` in `coordinator.ts:313-319`. Multi-level tree topology is not currently implemented — use pattern name for intent, but expect the same runtime graph. ### Additional Patterns (role-driven) These 14 additional patterns exist in `SwarmPattern` (types.ts:114-139). The coordinator has role-based auto-selection heuristics (`coordinator.ts:51-165`), but they only fire when `swarm.pattern` is **omitted** — YAML validation requires it (`runner.ts:2105-2117`), so auto-selection is effectively a programmatic-API feature. In YAML, set `swarm.pattern` explicitly. Topology is still resolved per-pattern once selected; the "Triggering roles" column reflects what the coordinator looks for to shape edges (per `coordinator.ts:250-450`): | Pattern | Roles the topology keys off | Topology | | ----------------- | ------------------------------------------------------- | ---------------------------------------------- | | `map-reduce` | `mapper` + `reducer` | coordinator → mappers → reducers → coordinator | | `scatter-gather` | — | hub → workers → hub | | `supervisor` | `supervisor` | supervisor ↔ workers | | `reflection` | `critic` or `reviewer` (auto-select uses `critic` only) | producers → critic → producers (loop) | | `red-team` | `attacker`/`red-team` + `defender`/`blue-team` | adversarial mesh with optional judges | | `verifier` | `verifier` | producers → verifiers → back to producers | | `auction` | `auctioneer` | auctioneer → bidders → auctioneer | | `escalation` | `tier-*` | tiered chain, escalate up / report down | | `saga` | `saga-orchestrator`, `compensate-handler` | orchestrator ↔ participants | | `circuit-breaker` | `primary` + `fallback`/`backup` | try primary, fallback on failure | | `blackboard` | `blackboard` / `shared-workspace` | shared state hub | | `swarm` | `hive-mind` / `swarm-agent` | stigmergy-style | | `competitive` | — (declared explicitly) | independent parallel implementations + judge | | `review-loop` | `implement*` + 2+ `reviewer*` | implementer ↔ reviewers | ### Structured Squad Review Loop - Split the work into bounded implementation squads. Each squad owns a non-overlapping file or subsystem scope. - Give each squad an implementer plus a shadow/review partner. The shadow follows the implementer in real time, checks alignment with the spec, and posts concise feedback before the work drifts. - Require the implementer to self-reflect before external review: compare the final diff against the spec, AGENTS.md / CLAUDE.md, recent local conventions, tests, and declared non-goals. - Run an independent self-review/fresh-eyes agent that reads the actual files and recent repo context, not just the chat transcript. - Send that review back to the implementer for one repair round. - After squads converge, run a final two-agent review team, usually one Claude reviewer and one Codex reviewer, independently. They compare notes, merge findings, and produce one final verdict. - Spawn fresh fix agents for final-review findings. Those fix agents self-reflect, then the final reviewers re-check the post-fix state until the spec is fully satisfied or a blocker is documented. - Use `supervisor` or `hub-spoke` when a lead needs to coordinate live squads. - Use `review-README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/agentworkforce-relay-agents-skills-choosing-swarm-patterns.md