claude-code-teams

What this skill does

# Claude Code Agent Teams Reference

A shared reference for Claude Code's Agent Teams features. Load this skill when building skills or agents that create teams, spawn teammates, coordinate multi-agent workflows, or integrate with team hooks.

This skill covers team lifecycle, tool parameters, spawning mechanics, and file structure. For deeper topics, load the reference files listed in [Loading Reference Files](#loading-reference-files).

> **Cross-reference**: For Claude Code Tasks (TaskCreate, TaskGet, TaskUpdate, TaskList), see the companion skill: `Read ${CLAUDE_PLUGIN_ROOT}/skills/claude-code-tasks/SKILL.md`

---

## TeamCreate Tool

Creates a new named team and registers the caller as team lead.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_name` | string | Yes | Unique team identifier. Used in file paths, environment variables, and member discovery. Use kebab-case (e.g., `analysis-team`). |
| `description` | string | No | Human-readable description of the team's purpose. Shown in team config and used by teammates to understand their team's mission. |
| `agent_type` | string | No | The type of agent running as team lead. Informational; stored in config.json for member discovery. |

**Return behavior**: Returns a confirmation with the team name. The team is immediately ready for member spawning after creation. Teams have a 1:1 correspondence with task lists — creating a team also creates a task list at `~/.claude/tasks/{team-name}/`. A `config.json` file is created at `~/.claude/teams/{team-name}/config.json` with team metadata including lead identity, description, and a `members` array where each member has `name`, `agentId`, and `agentType`.

**Constraints**:
- Team names must be unique across all active teams
- The creating agent becomes team lead automatically
- Only team leads can send shutdown requests to members

---

## TeamDelete Tool

Deletes a team and cleans up its resources. Takes no parameters — the team name is determined from the current session's team context.

**Prerequisites**: All team members must be shut down before deletion. Attempting to delete a team with active members will fail.

**Cleanup behavior**: Removes the team directory (`~/.claude/teams/{team-name}/`) and the task directory (`~/.claude/tasks/{team-name}/`), clears inbox directories, and deregisters the team.

---

## Team Lifecycle

The full lifecycle of an agent team follows seven steps:

```
Create Team --> Create Tasks --> Spawn Teammates --> Assign Tasks --> Work --> Shutdown --> Cleanup
```

```mermaid
stateDiagram-v2
    [*] --> Created: TeamCreate
    Created --> TasksReady: TaskCreate
    TasksReady --> Spawning: Agent tool (team_name, name)
    Spawning --> Assigning: TaskUpdate (owner)
    Spawning --> Spawning: Spawn more members
    Assigning --> Working: Teammates active
    Working --> Assigning: More tasks to assign
    Working --> ShuttingDown: All work complete
    ShuttingDown --> Cleanup: All members stopped
    Cleanup --> [*]: TeamDelete

    classDef active fill:#e8f5e9,color:#000
    classDef transition fill:#fff3e0,color:#000
    class Created,TasksReady,Cleanup transition
    class Spawning,Assigning,Working,ShuttingDown active
```

### Step Details

**1. Create team**: Team lead calls `TeamCreate` with a name. The team config file is written, a task list is created, and the lead is registered.

**2. Create tasks**: Team lead uses `TaskCreate` to add tasks. Tasks auto-use the team's task list at `~/.claude/tasks/{team-name}/`.

**3. Spawn teammates**: Team lead uses the `Agent` tool with `team_name` and `name` parameters to spawn teammates. Each teammate runs as an isolated Claude Code session. Members can be spawned incrementally as work demands change.

**4. Assign tasks**: Team lead uses `TaskUpdate` with `owner` to assign tasks to specific teammates.

**5. Teammates work**: Members complete assigned tasks, communicate via `SendMessage`, and report results. The team lead monitors progress, assigns new work, and handles issues. Members go idle between turns — this is normal, not an error.

**6. Shutdown**: When all work is complete, the team lead sends `shutdown_request` messages to each member. Members acknowledge with `shutdown_response` and terminate. The lead waits for all members to confirm shutdown.

**7. Cleanup**: After all members have stopped, the team lead calls `TeamDelete` to remove the team and task directories.

---

## Teammate Spawning

Teammates are spawned using the **Agent tool** with the `team_name` parameter. Each teammate runs as a separate Claude Code session.

> **Plugin tool name**: In Claude Code plugin frontmatter (`allowed-tools` in skills, `tools` in agents), the Agent tool is listed as `Task`. Both names refer to the same spawning capability with identical parameters (`prompt`, `team_name`, `name`, `description`, `subagent_type`, `run_in_background`). Use `Task` in frontmatter definitions and `Agent` or `Task` in skill/agent body instructions.

### Spawn Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prompt` | string | Yes | The task/prompt for the teammate. This is the initial instruction the teammate receives. |
| `team_name` | string | Yes | Associates the spawned agent with this team. Must match an existing team name. |
| `name` | string | Yes | Human-readable name for the teammate (e.g., `"researcher-1"`). Appears in team config and messages. |
| `description` | string | Yes | Short (3-5 word) description of the agent's task. |
| `subagent_type` | string | No | Model tier for the teammate: `"default"` (Opus), `"fast"` (Sonnet). Choose based on task complexity. |
| `run_in_background` | boolean | No | If `true`, the spawning agent does not block waiting for the teammate to finish. Essential for parallel teammate workflows. Default: `false`. |

### Subagent Type Selection

| Type | Model Tier | Best For |
|------|-----------|----------|
| `"default"` | Opus | Complex reasoning, synthesis, architecture decisions, autonomous multi-step work |
| `"fast"` | Sonnet | Parallel exploration, data gathering, straightforward implementation, high-volume tasks |

### Isolation

Each teammate runs in its own Claude Code session with:
- Independent context window (no shared memory with other teammates)
- Own tool permissions and approval state
- Own working directory (same project root)
- Communication only through `SendMessage` (file-based inbox delivery)

### Background Spawning Pattern

For parallel teammates, spawn all with `run_in_background: true`:

```
Task(prompt="Analyze module A", team_name="analysis-team", name="analyzer-1",
     description="Analyze module A", run_in_background=true)
Task(prompt="Analyze module B", team_name="analysis-team", name="analyzer-2",
     description="Analyze module B", run_in_background=true)
Task(prompt="Analyze module C", team_name="analysis-team", name="analyzer-3",
     description="Analyze module C", run_in_background=true)
```

Note: In skill/agent instructions, this tool may be referenced as either `Task` or `Agent`. Both are equivalent.

The team lead continues running and can coordinate via messages while teammates work.

---

## Idle State Semantics

Understanding idle state is critical for correct team coordination.

**Idle is normal, not an error.** When a teammate finishes its current task and has no pending messages, it enters an idle state. This is expected behavior between work assignments.

**Key rules**:
- Idle teammates can still receive and process messages
- Claude Code sends automatic idle notifications to the team lead when a teammate becomes idle
- Do NOT interpret idle as "broken" or "stuck" — it means the teammate is waiting for work
- Do NOT react to idle notifications unless you have new work to assign
- Send new work to idle teammates via `SendMessage` when ready
- Only send `shutdown_request` when the teammate's role is fully com