swarm-orchestrator

Swarm Orchestrator

An Agent Skill for Claude that designs, builds, and debugs multi-agent systems. Turn Claude into a swarm architect that creates cost-efficient, deterministic-first agent pipelines.

Built by Swarm Labs USA | GitHub

What It Does

This skill teaches Claude to architect multi-agent swarms:

• Design agent roles using 8 archetypes (Perceiver, Classifier, Analyzer, Synthesizer, Validator, Resolver, Planner, Executor)
• Orchestrate agents with 5 communication patterns (Sequential Chalkboard, Fan-Out/Fan-In, Pipeline with Gates, Adversarial Pair, Iterative Refinement)
• Optimize costs with the deterministic-first cascade — try rules before LLMs, start smallest
• Debug multi-agent failures with chalkboard trace analysis
• Validate pipeline definitions for cycles, schema mismatches, and budget violations
• Simulate pipeline execution to verify data flow before building

Why This Exists

Anthropic shipped agent teams in Opus 4.6. 123+ plugins in the marketplace. Zero of them teach how to design, orchestrate, or debug multi-agent systems.

This skill fills that gap with production-tested patterns. The architectures and patterns in this skill are extracted from real systems — see Production Validation below.

Quick Start

Install in Claude Code

# From GitHub
/plugin install github:michaelwinczuk/swarm-orchestrator

Basic Usage

"Design an agent swarm that monitors social media mentions,
 classifies sentiment, and drafts responses for negative ones."

"My pipeline has 12 agents costing $2/run. Help me optimize."

"Agent 3 and Agent 5 produce contradictory outputs. Debug this."

"Validate this pipeline definition for issues."

Core Concepts

8 Agent Archetypes

5 Communication Patterns

1. Sequential Chalkboard — Agents execute in order, read/write shared state. Default choice.
2. Fan-Out / Fan-In — Parallel independent analyses merged by a synthesizer.
3. Pipeline with Gates — Sequential with quality checkpoints that can halt/redirect.
4. Adversarial Pair — Advocate + Critic reviewed by a Resolver. For high-stakes decisions.
5. Iterative Refinement — Generate + validate loop with retry limits.

Deterministic-First Cascade

Rules/Code ($0) → Local Model ($0) → API Model ($0.02) → Frontier ($0.10+)

Always try the cheapest approach first. Most swarm operations don't need LLMs.

Chalkboard Protocol

Shared state that agents read from and write to:

• Agents can READ any previous agent's output
• Agents can only WRITE to their own section
• Each output is immutable once written
• The chalkboard is the single source of truth and your primary debugging tool

Production Validation

These patterns are extracted from systems built with the Swarm Labs ecosystem. Measured results from deployed swarms:

Math Swarm — Verified Benchmark

The Math Swarm is the strongest proof of the deterministic-first principle. Full results and code:

A 3B model + deterministic swarm outperforms a 32B model alone. The architecture matters more than the model size.

Project Structure

swarm-orchestrator/
├── SKILL.md                        # Core skill (loaded by Claude)
├── README.md                       # This file
├── LICENSE                         # Apache 2.0
├── scripts/
│   ├── validate_pipeline.py        # Pipeline definition validator
│   └── simulate.py                 # Chalkboard simulation engine
├── references/
│   ├── archetypes.md               # 8 agent archetypes with design rules
│   └── examples.md                 # 4 complete swarm designs + debugging example
└── evals/
    └── evals.json                  # 5 test cases

Swarm Labs Ecosystem

License

Apache 2.0 — See LICENSE for details.

Built by Michael Winczuk at Swarm Labs USA