Swarm Spawning Skill | Agent Skills

Swarm Spawning

How to create agents -- subagent vs teammate, agent type catalog, backend selection.

Two Ways to Spawn Agents

Method 1 -- Task Tool (Subagents)

Use Task for short-lived, focused work that returns a result:

Agent({
  subagent_type: "Explore",
  description: "Find auth files",
  prompt: "Find all authentication-related files in this codebase",
  model: "haiku"  // Optional: haiku, sonnet, opus
})

Characteristics:

Runs synchronously (blocks until complete) or async with run_in_background: true
Returns result directly to you
No team membership required
Best for searches, analysis, focused research

Method 2 -- Task Tool + team_name + name (Teammates)

Use Task with team_name and name to spawn persistent teammates:

// First create a team
TeamCreate({ team_name: "my-project" })

// Then spawn a teammate into that team
Agent({
  team_name: "my-project",        // Required -- which team to join
  name: "security-reviewer",      // Required -- teammate's name
  subagent_type: "general-purpose",
  prompt: "Review all authentication code for vulnerabilities. Send findings to team-lead.",
  run_in_background: true         // Teammates usually run in background
})

Characteristics:

Joins team, appears in config.json
Communicates via SendMessage
Can claim tasks from shared task list
Persists until shutdown
Best for parallel work, ongoing collaboration, pipeline stages

Choosing Between Subagent and Teammate

flowchart TD
    Start([Need to spawn an agent]) --> Q1{Does the agent need to collaborate with others?}
    Q1 -->|No -- independent work| Sub[Task subagent<br/>Returns result directly]
    Q1 -->|Yes -- team coordination| Q2{Does it need shared task list?}
    Q2 -->|Yes| Team[Task + team_name + name<br/>Full teammate]
    Q2 -->|No -- just messaging| Team
    Sub --> Done([Agent spawned])
    Team --> Done

Subagent -- lifespan until task complete, communication via return value, no task access, no team membership
Teammate -- lifespan until shutdown requested, communication via inbox messages, shared task list access, team membership, ongoing coordination

Built-in Agent Types

These are always available without plugins.

Bash

Agent({
  subagent_type: "Bash",
  description: "Run git commands",
  prompt: "Check git status and show recent commits"
})

Tools: Bash only
Model: Inherits from parent
Best for: Git operations, command execution, system tasks

Explore

Agent({
  subagent_type: "Explore",
  description: "Find API endpoints",
  prompt: "Find all API endpoints in this codebase. Be very thorough.",
  model: "haiku"  // Fast and cheap
})

Tools: All read-only tools (no Edit, Write, NotebookEdit, Task)
Model: Haiku (optimized for speed)
Best for: Codebase exploration, file searches, code understanding
Thoroughness levels: "quick", "medium", "very thorough"

Plan

Agent({
  subagent_type: "Plan",
  description: "Design auth system",
  prompt: "Create an implementation plan for adding OAuth2 authentication"
})

Tools: All read-only tools
Model: Inherits from parent
Best for: Architecture planning, implementation strategies

general-purpose

Agent({
  subagent_type: "general-purpose",
  description: "Research and implement",
  prompt: "Research React Query best practices and implement caching for the user API"
})

Tools: All tools
Model: Inherits from parent
Best for: Multi-step tasks, research + action combinations

claude-code-guide

Agent({
  subagent_type: "claude-code-guide",
  description: "Help with Claude Code",
  prompt: "How do I configure MCP servers?"
})

Tools: Read-only + WebFetch + WebSearch
Best for: Questions about Claude Code, Agent SDK, Anthropic API

statusline-setup

Agent({
  subagent_type: "statusline-setup",
  description: "Configure status line",
  prompt: "Set up a status line showing git branch and node version"
})

Tools: Read, Edit only
Model: Sonnet
Best for: Configuring Claude Code status line

Plugin Agent Types

From the compound-engineering plugin (examples):

Review Agents

// Security review
Agent({
  subagent_type: "compound-engineering:review:security-sentinel",
  description: "Security audit",
  prompt: "Audit this PR for security vulnerabilities"
})

// Performance review
Agent({
  subagent_type: "compound-engineering:review:performance-oracle",
  description: "Performance check",
  prompt: "Analyze this code for performance bottlenecks"
})

// Architecture review
Agent({
  subagent_type: "compound-engineering:review:architecture-strategist",
  description: "Architecture review",
  prompt: "Review the system architecture of the authentication module"
})

All review agents from compound-engineering:

agent-native-reviewer -- Ensures features work for agents too
architecture-strategist -- Architectural compliance
code-simplicity-reviewer -- YAGNI and minimalism
data-integrity-guardian -- Database and data safety
data-migration-expert -- Migration validation
deployment-verification-agent -- Pre-deploy checklists
dhh-rails-reviewer -- DHH/37signals Rails style
julik-frontend-races-reviewer -- JavaScript race conditions
kieran-python-reviewer -- Python best practices
kieran-rails-reviewer -- Rails best practices
kieran-typescript-reviewer -- TypeScript best practices
pattern-recognition-specialist -- Design patterns and anti-patterns
performance-oracle -- Performance analysis
security-sentinel -- Security vulnerabilities

Research Agents

// Best practices research
Agent({
  subagent_type: "compound-engineering:research:best-practices-researcher",
  description: "Research auth best practices",
  prompt: "Research current best practices for JWT authentication"
})

// Framework documentation
Agent({
  subagent_type: "compound-engineering:research:framework-docs-researcher",
  description: "Research Active Storage",
  prompt: "Gather comprehensive documentation about Active Storage file uploads"
})

// Git history analysis
Agent({
  subagent_type: "compound-engineering:research:git-history-analyzer",
  description: "Analyze auth history",
  prompt: "Analyze the git history of the authentication module"
})

All research agents:

best-practices-researcher -- External best practices
framework-docs-researcher -- Framework documentation
git-history-analyzer -- Code archaeology
learnings-researcher -- Search docs/solutions/
repo-research-analyst -- Repository patterns

Design Agents

Agent({
  subagent_type: "compound-engineering:design:figma-design-sync",
  description: "Sync with Figma",
  prompt: "Compare implementation with Figma design at [URL]"
})

Workflow Agents

Agent({
  subagent_type: "compound-engineering:workflow:bug-reproduction-validator",
  description: "Validate bug",
  prompt: "Reproduce and validate this reported bug: [description]"
})

Spawn Backends

A backend determines how teammate Claude instances actually run. Claude Code supports three backends and auto-detects the best one.

Auto-Detection Logic

flowchart TD
    A[Start] --> B{Running inside tmux?}
    B -->|Yes| C[Use tmux backend]
    B -->|No| D{Running in iTerm2?}
    D -->|No| E{tmux available?}
    E -->|Yes| F[Use tmux - external session]
    E -->|No| G[Use in-process]
    D -->|Yes| H{it2 CLI installed?}
    H -->|Yes| I[Use iterm2 backend]
    H -->|No| J{tmux available?}
    J -->|Yes| K[Use tmux - prompt to install it2]
    J -->|No| L[Error -- Install tmux or it2]

Detection checks:

$TMUX environment variable -- inside tmux
$TERM_PROGRAM === "iTerm.app" or $ITERM_SESSION_ID -- in iTerm2
which tmux -- tmux available
which it2 -- it2 CLI installed

in-process (Default for non-tmux)

Teammates run as async tasks within the same Node.js process.

No new process spawned
Teammates share the same Node.js event loop
Communication via in-memory queues (fast)
You don't see teammate output directly

+---------------------------------------+
|           Node.js Process             |
|  +---------+  +---------+  +---------+|
|  | Leader  |  |Worker 1 |  |Worker 2 ||
|  | (main)  |  | (async) |  | (async) ||
|  +---------+  +---------+  +---------+|
+---------------------------------------+

Pros: Fastest startup, lowest overhead, works everywhere Cons: Can't see teammate output in real-time, all die if leader dies, harder to debug

tmux

Teammates run as separate Claude instances in tmux panes/windows.

Each teammate gets its own tmux pane
Separate process per teammate
Communication via inbox files

+-----------------+-----------------+
|                 |    Worker 1     |
|     Leader      +-----------------+
|   (your pane)   |    Worker 2     |
|                 +-----------------+
|                 |    Worker 3     |
+-----------------+-----------------+

Pros: See teammate output in real-time, teammates survive leader exit, works in CI/headless Cons: Slower startup (process spawn), requires tmux installed, more resource usage

Useful tmux commands:

# List all panes in current window
tmux list-panes

# Switch to pane by number
tmux select-pane -t 1

# Kill a specific pane
tmux kill-pane -t %5

# View swarm session (if external)
tmux attach -t claude-swarm

# Rebalance pane layout
tmux select-layout tiled

iterm2 (macOS only)

Teammates run as split panes within your iTerm2 window.

Uses iTerm2's Python API via it2 CLI
Each teammate visible side-by-side
Communication via inbox files

Setup:

# 1. Install it2 CLI
uv tool install it2

# 2. Enable Python API in iTerm2
# iTerm2 > Settings > General > Magic > Enable Python API

# 3. Restart iTerm2

# 4. Verify
it2 --version
it2 session list

Pros: Visual debugging, native macOS experience, no tmux needed Cons: macOS + iTerm2 only, requires setup, panes die with window

Forcing a Backend

# Force in-process (fastest, no visibility)
export CLAUDE_CODE_SPAWN_BACKEND=in-process

# Force tmux (visible panes, persistent)
export CLAUDE_CODE_SPAWN_BACKEND=tmux

# Auto-detect (default)
unset CLAUDE_CODE_SPAWN_BACKEND

Backend in Team Config

The backend type is recorded per-teammate in config.json:

{
  "members": [
    {
      "name": "worker-1",
      "backendType": "in-process",
      "tmuxPaneId": "in-process"
    },
    {
      "name": "worker-2",
      "backendType": "tmux",
      "tmuxPaneId": "%5"
    }
  ]
}

Environment Variables

Spawned teammates automatically receive these:

CLAUDE_CODE_TEAM_NAME="my-project"
CLAUDE_CODE_AGENT_ID="worker-1@my-project"
CLAUDE_CODE_AGENT_NAME="worker-1"
CLAUDE_CODE_AGENT_TYPE="Explore"
CLAUDE_CODE_AGENT_COLOR="#4A90D9"
CLAUDE_CODE_PLAN_MODE_REQUIRED="false"
CLAUDE_CODE_PARENT_SESSION_ID="session-xyz"

Using in prompts:

Agent({
  team_name: "my-project",
  name: "worker",
  subagent_type: "general-purpose",
  prompt: "Your name is $CLAUDE_CODE_AGENT_NAME. Use it when sending messages to team-lead."
})

Troubleshooting Backends

"No pane backend available" -- Neither tmux nor iTerm2 available. Install tmux.
"it2 CLI not installed" -- In iTerm2 but missing it2. Run uv tool install it2.
"Python API not enabled" -- it2 can't communicate with iTerm2. Enable in iTerm2 Settings > General > Magic.
Workers not visible -- Using in-process backend. Start inside tmux or iTerm2.
Workers dying unexpectedly -- Outside tmux, leader exited. Use tmux for persistence.

Checking current backend:

# Check if inside tmux
echo $TMUX

# Check if in iTerm2
echo $TERM_PROGRAM

# Check tmux availability
which tmux

# Check it2 availability
which it2

Related Skills

Core concepts -- Skill(skill: "swarm-primitives")
API reference -- Skill(skill: "swarm-operations")
Patterns and recipes -- Skill(skill: "swarm-patterns")

SOURCE: Claude Code v2.1.45 tool descriptions (TeamCreate, Task) -- verified 2026-02-18

Agent Skills: Swarm Spawning

Install this agent skill to your local

Skill Files