# Claude Code Swarm Orchestration Skill Guide

> Complete reference skill for multi-agent swarm orchestration in Claude Code. Covers TeammateTool API, 6 orchestration patterns, spawn backends, and error handling.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

Save as `~/.claude/skills/swarm-orchestration/SKILL.md` or:

```bash
# Copy from gist
curl -o ~/.claude/skills/swarm-orchestration/SKILL.md \
  https://gist.githubusercontent.com/kieranklaassen/4f2aba89594a4aea4ad64d753984b2ea/raw/SKILL.md
```

## 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 feedback
```

### 2. Pipeline

```
research → plan → implement → test → review
Each stage depends on the previous, with Task dependencies
```

### 3. Swarm (Self-Organizing)

```
Leader creates task pool → Workers grab tasks from shared list
No fixed assignment — agents self-organize based on capacity
```

### 4. Research + Implementation

```
Research agent gathers context synchronously
Implementation agent uses research output
```

### 5. Plan Approval Workflow

```
Architect designs → Leader reviews and approves/rejects
Only approved plans proceed to implementation
```

### 6. Coordinated Multi-File Refactoring

```
Leader creates shared spec → Parallel workers refactor their assigned files
Workers reference spec for consistency
```

## Spawn 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.

## Source & Thanks

> Created by [Kieran Klaassen](https://gist.github.com/kieranklaassen). Based on Claude Code v2.1.19.
>
> [Original Gist](https://gist.github.com/kieranklaassen/4f2aba89594a4aea4ad64d753984b2ea)

<!-- ZH -->


## Quick Start

Save as `~/.claude/skills/swarm-orchestration/SKILL.md`.

## What Is This Skill?

A complete reference for Claude Code multi-agent coordination — covering the TeammateTool API, 6 orchestration patterns, spawn backends, and error handling.

**In one sentence**: Claude Code Swarm orchestration Skill — TeammateTool (13 operations) + 6 orchestration patterns (parallel/pipeline/swarm/research/approval/refactor). Essential for multi-agent collaboration.

**For**: Developers using Claude Code Agent Teams.

## Core Content

### TeammateTool 13 Operations
spawnTeam, write, broadcast, requestShutdown, and other team management operations.

### 6 Orchestration Patterns
1. Parallel Experts — multiple reviewers review simultaneously
2. Pipeline — serial dependent stages
3. Swarm — self-organizing task pool
4. Research + Implement — research-driven synchronized implementation
5. Approval Workflow — architect designs, leader approves
6. Multi-File Coordinated Refactor

## FAQ

**Q: How many agents can run concurrently?**
A: Typically 3-8, depending on hardware.

## Source & Thanks

> [Kieran Klaassen Gist](https://gist.github.com/kieranklaassen/4f2aba89594a4aea4ad64d753984b2ea)

---
Source: https://tokrepo.com/en/workflows/claude-code-swarm-orchestration-skill-guide-e07746ff
Author: Skill Factory