launching-agent-teams

STARTER_CHARACTER = 🚀👥

Setup

Update reference docs to get the latest from Anthropic:

python ${CLAUDE_SKILL_DIR}/scripts/update-docs.py

Prerequisites

Agent teams are experimental. The user must have this in their settings (~/.claude/settings.json or .claude/settings.json):

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

If the flag isn't set, tell the user and offer to add it before proceeding.

Teams vs Subagents — Pick the Right Tool

Before launching a team, confirm it's the right approach:

Use agent teams when:

• Teammates need to communicate with each other
• Work benefits from debate, challenge, or cross-pollination
• Tasks span multiple independent areas (frontend/backend/tests)
• Investigation needs competing hypotheses

Use subagents instead when:

• Workers just report results back (no inter-agent communication)
• Tasks are focused and self-contained
• You want lower token cost
• Sequential dependency between steps

Use git worktrees when:

• You want manual parallel sessions without automated coordination

If the task fits subagents better, say so and offer that instead.

Launching a Team

1. Clarify the Work

Before spawning anything, understand:

• What's the goal?
• What are the independent pieces?
• What would each teammate own?

2. Decompose Into Roles

Each teammate should own a distinct, non-overlapping area. Overlap causes file conflicts and wasted tokens.

Aim for 3-5 teammates. More than that creates coordination overhead that rarely pays off. Each teammate should have 5-6 tasks to stay productive.

Anti-patterns:

• Two teammates editing the same file
• A teammate with only one small task (just do it yourself)
• Roles so broad they inevitably overlap

3. Size Tasks Appropriately

• Too small: coordination overhead exceeds the benefit
• Too large: teammates work too long without check-ins
• Right size: self-contained units with a clear deliverable (a function, a test file, a review document)