agent-teams

name	agent-teams
description	Use when the user is NEW to Claude Code agent teams or asks high-level questions about what they are, when to use them, or how they compare to subagents. Triggers: "how do agent teams work", "what are agent teams", "agent teams vs subagents", "should I use a team for this", "are agent teams enabled". Do NOT trigger for choosing a specific team blueprint (route to `team-blueprints`) or managing an active team (route to `team-coordination`). This skill is the onboarding / discovery entry point only.
version	0.26.0

Agent Teams — Overview

Agent teams coordinate multiple Claude Code sessions on complex tasks. One session is the team lead (coordinates work); teammates work independently in their own context windows and message each other directly.

When agent teams add value

Use Case	Why Teams Excel
Research & Discovery	Multiple teammates investigate different aspects simultaneously
Feature Development	Each teammate owns a separate module — no file conflicts
Code Review & QA	Reviewers apply different lenses (security, performance, tests) in parallel
Debugging	Teammates test competing hypotheses and challenge each other
Cross-Layer Coordination	Frontend, backend, and tests each owned by a different teammate

Agent Teams vs Subagents

Aspect	Subagents	Agent Teams
Context	Own window; results return to caller	Own window; fully independent
Communication	Report back to main agent only	Teammates message each other directly
Coordination	Main agent manages all work	Shared task list with self-coordination
Best for	Focused tasks where only the result matters	Complex work requiring discussion and collaboration
Token cost	Lower (results summarized back)	Higher (each teammate is a separate instance)

Rule of thumb: Use subagents for quick focused workers. Use agent teams when teammates need to share findings, challenge each other, and coordinate independently.

When NOT to use a team

Teams add ~40 coordination tool calls of overhead per team. Skip teams when:

• Fewer than 3 genuinely parallel workstreams
• A single agent can hold all necessary context
• The task is primarily sequential
• Total expected work is under ~30 minutes

Sizing guidelines and per-blueprint compositions are documented in team-blueprints (skill) and ${CLAUDE_PLUGIN_ROOT}/shared/efficiency-guidelines.md.

Prerequisites

Agent teams are experimental and must be enabled:

// settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Quick Start

/spawn-build add user authentication with OAuth and JWT
/spawn-think evaluate React state management libraries
/spawn-create brainstorm API authentication approaches

Or describe the task in natural language and Claude will propose a team.

Where to go next

You want to...	Skill / Command
See pre-designed team configurations for 8 development phases	team-blueprints skill
Apply deep behavioral profiles (Auditor, Architect, Refiner, etc.) to teammates	team-personas skill
Manage an active team (tasks, communication, shutdown)	team-coordination skill
Spawn a build team (feature or debug)	/spawn-build command
Spawn a think team (research, planning, or review)	/spawn-think command
Spawn a create team (design, brainstorm, or productivity)	/spawn-create command
Wrap related spawns in a multi-stage project pipeline	/project command
Design a custom team that doesn't match a blueprint	team-architect agent

Reference

For complete API documentation, tool descriptions, architecture, and the full pattern catalog, see references/agent-teams-reference.md.