What is This Skill?
This is a comprehensive SKILL.md reference for Claude Code's multi-agent orchestration system. It documents the TeammateTool API, Task system, spawn backends, and provides 6 ready-to-use orchestration patterns. Install this skill to give Claude Code deep knowledge of how to coordinate multiple agents for parallel work.
Answer-Ready: Claude Code Swarm Orchestration Skill — complete reference for multi-agent coordination. Covers TeammateTool API (13 operations), 6 orchestration patterns (parallel, pipeline, swarm, research), spawn backends (tmux, iTerm2), and error handling. Essential for agent teams.
Best for: Developers using Claude Code agent teams for complex tasks. Works with: Claude Code v2.1+. Setup time: Under 1 minute.
Core Concepts
Agent Primitives
| Primitive | Description |
|---|---|
| Agent | A running Claude Code instance |
| Team | Named group of agents with shared config |
| Teammate | Agent that is a member of a team |
| Leader | Agent that spawned the team |
| Task | Unit of work with status tracking |
| Inbox | JSON message queue per agent |
TeammateTool Operations (13)
| Operation | Purpose |
|---|---|
| spawnTeam | Create new team with members |
| discoverTeams | Find existing teams |
| requestJoin | Ask to join a team |
| approveJoin / rejectJoin | Handle join requests |
| write | Send message to agent inbox |
| broadcast | Send message to all team members |
| requestShutdown | Initiate graceful shutdown |
| approveShutdown / rejectShutdown | Handle shutdown |
| approvePlan / rejectPlan | Plan approval workflow |
| cleanup | Remove team resources |
6 Orchestration Patterns
1. Parallel Specialists
Leader spawns: security-reviewer, perf-reviewer, style-reviewer
Each reviews code independently → Leader merges feedback2. Pipeline
research → plan → implement → test → review
Each stage depends on the previous, with Task dependencies3. Swarm (Self-Organizing)
Leader creates task pool → Workers grab tasks from shared list
No fixed assignment — agents self-organize based on capacity4. Research + Implementation
Research agent gathers context synchronously
Implementation agent uses research output5. Plan Approval Workflow
Architect designs → Leader reviews and approves/rejects
Only approved plans proceed to implementation6. Coordinated Multi-File Refactoring
Leader creates shared spec → Parallel workers refactor their assigned files
Workers reference spec for consistencySpawn Backends
| Backend | Visibility | Survives Exit | Best For |
|---|---|---|---|
| in-process | Hidden | No | Fast, simple tasks |
| tmux | Visible panes | Yes | Long-running, monitoring |
| iterm2 | Split panes | Yes | macOS development |
Error Handling
- Crashed teammates auto-marked inactive after 5-minute heartbeat timeout
- Graceful shutdown: requestShutdown all → wait for approvals → verify no active members → cleanup
- Task retry with exponential backoff
FAQ
Q: How many agents can run simultaneously? A: Depends on hardware. Typical: 3-8 agents on a modern machine. Each agent uses ~200MB RAM.
Q: Which pattern should I use? A: Parallel Specialists for code review, Pipeline for feature development, Swarm for large refactors.
Q: Do agents share context? A: Agents communicate via inboxes (JSON messages) and shared task lists. They do NOT share conversation context.