agent-teams

Agent Teams

Experimental: Agent teams require CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 and may change between Claude Code versions.

BREAKING (Claude Code 2.1.178): The explicit TeamCreate / TeamDelete tools were removed. Every session now has one implicit team when CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set — there is nothing to create or tear down. The team_name parameter is still accepted but ignored on the tools that took it (e.g. Agent), so older invocations don't error; omit it in new code. Coordination is otherwise unchanged: spawn teammates with the Agent tool, coordinate with SendMessage, and track work with TaskCreate/TaskList/TaskUpdate.

For the worked setup examples, communication snippets, shutdown procedures, the worktree path-resolution recovery routine, and common dispatch patterns, see REFERENCE.md.

When to Use This Skill

Sub-Agent Caveat: Spawn Teams from the Main Thread

Agent and the related parallel-spawn tools may not be present in a sub-agent's tool surface, even if the parent conversation has them. A sub-agent designed to orchestrate its own team can silently degrade to sequential single-thread execution — same content, ~5× longer wall-clock — without surfacing the failure until its post-completion summary.

Detection contract to brief into a coordinating sub-agent: confirm the Agent tool is callable; if not, do not silently fall back — report "Parallel fan-out unavailable in this sandbox; executed sequentially." as the first line of the summary, then continue sequentially with the same input contract. Plan top-level orchestration in the main conversation when you can.

Native Team Tools

The implicit team (2.1.178) needs no create/delete step — these tools operate on the one team the session already has:

The setup sequence — TaskCreate → spawn teammates via the Agent tool (with a name) → TaskUpdate to assign → receive results automatically — is shown with full code in REFERENCE.md → Team setup workflow. Teammate messages are delivered to the lead's inbox between turns; no polling needed.

Task Management

Teammates claim tasks in ID order (lowest first) via TaskList + TaskUpdate, and skip blocked tasks until their blocker completes.

Communication (SendMessage)

DM, broadcast, and discovery (Read ~/.claude/teams/<name>/config.json → members) examples are in REFERENCE.md → Communication.

Key Teammate Rules

• Mark exactly ONE task in_progress at a time.
• Use TaskUpdate (not SendMessage) to report task completion.
• Idle after every turn is normal — idle ≠ unavailable; a message wakes a teammate.
• All communication requires SendMessage — plain text output is NOT visible to the lead.
• Use the name field (not agentId) for recipient.

Lead Preflight Checklist

Before drafting the PRP and launching agents, a 30-second sweep prevents multi-edit renaming work after agents return:

Out-of-Scope Discovery Protocol

Include the out-of-scope discovery protocol in every agent's prompt when that agent has an exclusive write scope — it prevents the "investigate out of scope → exhaust budget → truncated summary" failure mode. Copy the verbatim block from REFERENCE.md → Out-of-scope discovery protocol: the agent stops immediately on an out-of-scope dependency, lists it under an Out-of-scope dependencies summary section, and exits for the lead to triage.

Worktree Isolation Hazard

Worktree-isolated agents can have Edit/Write silently resolve relative paths against the parent repo instead of their worktree (upstream bug #1091), landing commits on the wrong branch with no immediate signal. Harden every worktree-isolated prompt with the absolute-path preamble, run the lead post-flight check (git diff origin/main..HEAD + git status --porcelain from the parent), and use the cherry-pick + rebase recovery — all in REFERENCE.md → Worktree path resolution. See also .claude/rules/agent-coworker-detection.md.

Resuming Worktree-Isolated Agents

SendMessage-resume of a completed worktree-isolated agent (Agent with isolation: "worktree") loses worktree isolation — the resumed run executes in the orchestrator's main checkout, not the worktree. For parallel file-mutating work, re-dispatch a fresh isolation: "worktree" agent instead of resuming; reserve SendMessage-resume for read-only / single-checkout continuations. See parallel-agent-dispatch → "Resuming agents: SendMessage loses worktree isolation" (issue #1546).

Sandbox Considerations

In web sessions (CLAUDE_CODE_REMOTE=true):

• Sub-agents (teammates) may encounter TLS errors on git push — delegate all push/PR operations to the lead.
• Each teammate runs in its own process context.
• Worktree isolation is recommended for independent filesystem changes.

Quick Reference

Workflow Checklist

• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 set (the implicit team exists; no create step)
• TaskCreate for each work unit
• Spawn teammates via the Agent tool with a name (no team_name needed)
• TaskUpdate to assign tasks (or let teammates self-assign)
• Receive messages automatically; respond via SendMessage
• SendMessage shutdown_request to each teammate when done (no TeamDelete)

Key Paths

Address teammates by the name you gave them at spawn — that is the reliable handle, independent of any on-disk layout.

Common Mistakes

Related Skills and Rules

• parallel-agent-dispatch — worktree preflight, scope budgets, and the Return Contract every teammate must emit on exit. Team dispatches are a superset of plain parallel fan-out; follow both.
• .claude/rules/agent-development.md — agent file structure, model selection, worktree isolation
• .claude/rules/agentic-permissions.md — granular tool permission patterns
• .claude/rules/sandbox-guidance.md — web sandbox constraints and push delegation