Agent Teams — Orchestration Skill

Prerequisite: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 must be set in env or settings.json. Minimum version: Claude Code v2.1.32+

What This Skill Does

This skill creates, manages, and coordinates Claude Code agent teams. Agent teams are multiple independent Claude Code sessions that share a task list, communicate directly with each other, and work in parallel.

Unlike subagents (which run within a single session and only report back), agent team teammates are fully independent sessions that can message each other, self-claim tasks, and debate findings.

When to Use Agent Teams vs Subagents

Token warning: Agent teams use significantly more tokens than a single session. Each teammate has its own context window. Only use teams when parallel work genuinely adds value.

Creating a Team

Parse $ARGUMENTS for the task description and desired team structure. If not provided, ask the user what they want the team to accomplish.

Step 1: Determine Team Structure

Based on the task, decide:

1. Number of teammates (default 3-5, the sweet spot)
2. Roles for each teammate (distinct, non-overlapping)
3. File ownership per teammate (critical — two teammates editing the same file = overwrites)
4. Task dependencies (which tasks must complete before others can start)

Sizing rule: 5-6 tasks per teammate keeps everyone productive without excessive context switching. If you have 15 independent tasks, 3 teammates is right.

Step 2: Spawn the Team

Tell Claude to create the team in natural language. The lead (your current session) coordinates everything.

For each teammate, the spawn prompt MUST include:

• Their specific role and responsibilities
• Which files/directories they OWN (exclusive edit rights)
• Which files they may READ but not edit
• What deliverable they produce
• Any constraints or quality gates
• The full task context (teammates do NOT inherit conversation history)

Spawn prompt template:

You are the [role] teammate. Your job is to [specific task].

Files you OWN (only you edit these):
- [path/to/dir/]
- [path/to/file]

Files you may READ but NOT edit:
- [shared files]

Dependencies:
- You depend on: [teammate X finishing Y]
- Others depend on you for: [interface Z]

Definition of done:
- [ ] Implementation complete
- [ ] Tests pass
- [ ] Send summary to lead

Step 3: Model Selection

• Lead: Opus (coordination, synthesis, architecture decisions)
• Straightforward implementation teammates: Sonnet (saves tokens)
• Complex reasoning teammates: Opus (architecture, debugging)

Specify per-teammate: "Use Sonnet for the implementation teammates and Opus for the architect."

Step 4: Plan Approval (optional, for risky work)

Require teammates to plan before implementing:

Spawn an architect teammate to refactor auth. Require plan approval before changes.

The teammate works read-only until the lead approves their plan. If rejected, they revise and resubmit. Influence the lead's judgment with criteria: "only approve plans that include test coverage."

Common Team Patterns

1. Parallel Code Review → /team-review

Create a team to review PR #N with three reviewers:
- Security reviewer (OWASP, injection, secrets)
- Performance reviewer (complexity, queries, memory)
- Correctness & test reviewer (logic, edge cases, coverage)
Have them report findings independently, then I'll synthesize.

2. Competing Hypothesis Debug → /team-debug

Users report [bug symptoms]. Spawn 3-5 investigators, each with a different
hypothesis. Have them challenge each other's theories like a scientific debate.

3. Parallel Feature Build → /team-build

Create a team to implement [feature]. Split into:
- Backend teammate (owns src/api/)
- Frontend teammate (owns src/components/)
- Test teammate (owns tests/)
Each teammate works independently on their layer.

4. Research & Explore

Create a team to explore [topic] from different angles:
- UX implications teammate
- Technical architecture teammate
- Devil's advocate teammate

Managing the Team

Display Modes

Set via: claude --teammate-mode in-process or teammateMode in settings.json. "auto" (default) uses split panes if already in tmux, otherwise in-process.

Talking to Teammates Directly

• In-process: Shift+Down to cycle through teammates, type to message. Enter to view session, Escape to interrupt. Ctrl+T toggles task list.
• Split-pane: Click into a teammate's pane to interact directly.

Task Coordination

• Lead creates tasks; teammates self-claim or get assigned
• Tasks have states: pending → in_progress → completed
• Tasks can have dependencies (blocked until deps complete)
• Task claiming uses file locking to prevent race conditions

If the Lead Tries to Do Work Itself

Wait for your teammates to complete their tasks before proceeding.

Shutting Down Teammates

Ask the [name] teammate to shut down.

Teammates finish their current request before shutting down.

Cleanup (ALWAYS via the lead)

Clean up the team.

Important: Shut down ALL teammates first, then clean up. Teammates should never run cleanup — only the lead. If any teammates are still running, cleanup will fail.

Quality Gate Hooks

• TeammateIdle: Runs when a teammate goes idle. Exit code 2 = send feedback and keep teammate working.
• TaskCompleted: Runs when a task is marked complete. Exit code 2 = reject completion with feedback.

Architecture Reference

Permissions

Teammates inherit the lead's permission settings at spawn. You can change individual teammate modes after spawning, but not at spawn time. If the lead uses --dangerously-skip-permissions, all teammates do too.

Context & Communication

• Each teammate loads the same project context as a regular session: CLAUDE.md, MCP servers, skills
• Teammates receive the spawn prompt from the lead but NOT the lead's conversation history
• Automatic message delivery: messages arrive at recipients automatically
• Idle notifications: teammates notify the lead when they finish
• Messaging modes: message (to one teammate) or broadcast (to all — use sparingly, tokens scale with team size)

Anti-Patterns to Avoid

1. Two teammates editing the same file — guaranteed conflicts, always assign file ownership
2. Too many small tasks — coordination overhead exceeds benefit
3. Not enough context in spawn prompts — teammates don't inherit history, include everything they need
4. Lead doing implementation instead of coordinating — tell it to wait for teammates
5. Running unattended too long — check in, redirect approaches that aren't working
6. Overscaling — 3 focused teammates often outperform 5 scattered ones

Limitations

• No session resumption for in-process teammates (/resume won't restore them)
• One team per session
• No nested teams (teammates can't spawn their own teams)
• Lead is fixed for the team's lifetime (can't promote a teammate)
• All teammates start with lead's permission mode
• Split panes require tmux or iTerm2 (not VS Code terminal, Windows Terminal, or Ghostty)
• Task status can lag — check manually if something looks stuck
• Shutdown can be slow (teammates finish current work first)

Example Invocations

/team create 3 teammates to refactor the physics pipeline
/team investigate why tests are flaky with 4 competing hypotheses
/team review PR #142 with security, performance, and correctness reviewers
/team explore authentication approaches: OAuth, passkeys, and magic links
/team build the resource UID cache with backend + scene + test teammates using Sonnet