Claude Code Swarm Orchestration Skill Guide

What it is

The Swarm Orchestration skill is a reference guide for building multi-agent systems within Claude Code. It documents the TeammateTool API for spawning subagents, six orchestration patterns (fan-out, pipeline, supervisor, consensus, map-reduce, and recursive), spawn backend options, and error handling strategies. The skill file is installed into your Claude Code skills directory and activates when you work on multi-agent workflows.

This skill targets developers building complex AI systems where a single agent is insufficient -- scenarios requiring parallel research, multi-step validation, or coordinated code changes across a large codebase.

How it saves time or tokens

Without this skill, developers must discover the TeammateTool API and orchestration patterns through trial and error. The skill provides tested patterns with correct parameter names, error handling, and concurrency limits. This means Claude Code generates working multi-agent code on the first attempt rather than producing broken spawn calls that fail at runtime.

How to use

1. Save the skill file to your Claude Code skills directory:

mkdir -p ~/.claude/skills/swarm-orchestration
curl -o ~/.claude/skills/swarm-orchestration/SKILL.md \
  https://gist.githubusercontent.com/kieranklaassen/4f2aba89594a4aea4ad64d753984b2ea/raw/SKILL.md

1. Or install via Claude Code:

claude skill install swarm-orchestration

1. Ask Claude Code to build multi-agent workflows -- it will automatically reference the skill patterns.

Example

# Fan-out pattern: parallel research agents
from claude_code import TeammateTool

# Spawn 3 research agents in parallel
tasks = [
    TeammateTool.spawn(
        name='researcher-1',
        prompt='Research React state management libraries',
        background=True
    ),
    TeammateTool.spawn(
        name='researcher-2',
        prompt='Research Vue state management libraries',
        background=True
    ),
    TeammateTool.spawn(
        name='researcher-3',
        prompt='Research Svelte state management libraries',
        background=True
    ),
]

# Collect results
results = [task.wait() for task in tasks]

# Synthesize findings
TeammateTool.spawn(
    name='synthesizer',
    prompt=f'Compare these findings: {results}'
)

Related on TokRepo

• Multi-agent frameworks -- Compare orchestration frameworks including LangGraph, CrewAI, and AutoGen
• AI tools for coding -- Developer tools for AI-assisted programming

Common pitfalls

• Spawning too many concurrent agents exhausts API rate limits; the skill recommends a maximum of 5 parallel spawns
• Subagent errors do not propagate to the parent by default; always check return status before using results
• The skill file must be in the correct directory structure (~/.claude/skills/<name>/SKILL.md) or Claude Code will not detect it