| name | agent-teams |
| description | Orchestrate agent teams for parallelizable multi-faceted tasks. Use when work requires inter-agent communication, competing hypotheses, or multi-file parallel implementation. |
Agent Teams
Orchestrate collaborative agent teams using Claude Code's experimental agent teams feature.
When to Use
Is the work parallelizable with inter-agent communication needs?
├─ Single focused output? → Use a subagent (Task tool), not a team
├─ 2-3 independent outputs? → Use parallel subagents, not a team
├─ Parallel work + agents need to share findings? → USE A TEAM
├─ Competing hypotheses to test? → USE A TEAM
├─ Multi-file implementation with integration? → USE A TEAM
└─ Multi-lens review (security + perf + correctness)? → USE A TEAM
Don't use teams for: simple delegation, single-file work, sequential tasks, or anything a subagent handles fine.
The Process
Step 1: Assess the Task
Before spawning a team, answer:
- Can the work be split into 2-5 genuinely independent streams?
- Will agents need to communicate mid-task (not just return results)?
- Is there a clear integration point where results come together?
If any answer is "no", use subagents instead.
Step 2: Design the Team
Choose a pattern (see below) and define:
- Roles: What each teammate focuses on (be specific)
- File ownership: Which files each teammate can edit (CRITICAL — no overlaps)
- Deliverables: What each teammate produces
- Communication plan: When teammates should message vs. work independently
Step 3: Spawn with Context
Each teammate starts with zero context. Their spawn prompt must include:
- The overall goal and their specific role
- File paths they own (and must NOT touch)
- Expected deliverable format
- When to message the lead vs. work independently
Teammate tool → operation: "spawnTeam", team_name: "<descriptive-name>"
Task tool → team_name: "<name>", name: "<role>", subagent_type: "general-purpose"
Step 4: Coordinate
- Create tasks with TaskCreate before or after spawning
- Assign tasks with TaskUpdate (set
owner to teammate name)
- Use SendMessage
type: "message" for targeted communication
- Avoid broadcast unless truly team-wide critical information
- Monitor progress via TaskList — don't poll teammates
Step 5: Integrate & Clean Up
- Review all teammate outputs
- Integrate results (you, the lead, handle merging)
- Send
shutdown_request to each teammate
- Call
Teammate cleanup to remove team resources
- Commit the integrated work
Team Patterns
Research Team
When: Exploring a problem space, literature review, multi-angle analysis.
Composition (3-5 teammates):
| Role | Focus | Deliverable |
|---|
| Literature Scout | Find relevant prior work | Annotated reference list |
| Methodology Analyst | Evaluate approaches | Pros/cons comparison table |
| Devil's Advocate | Challenge assumptions | Counter-arguments and risks |
| Synthesizer | Integrate findings | Unified recommendation |
See research-team-prompt.md for spawn template.
Implementation Team
When: Building a feature that spans multiple files/modules with clear boundaries.
Composition (2-4 teammates):
| Role | Focus | Deliverable |
|---|
| Backend Dev | API routes, data layer | Working endpoints |
| Frontend Dev | UI components, state | Working interface |
| Test Writer | Test coverage | Passing test suite |
| Lead (you) | Integration, review | Merged feature |
Critical: Assign file ownership explicitly. No two teammates edit the same file.
See implementation-team-prompt.md for spawn template.
Debugging Team
When: Complex bug with multiple plausible root causes.
Composition (3-5 teammates):
| Role | Focus | Deliverable |
|---|
| Hypothesis A | Investigate theory A | Evidence for/against |
| Hypothesis B | Investigate theory B | Evidence for/against |
| Hypothesis C | Investigate theory C | Evidence for/against |
| Reproducer | Create minimal repro | Reproducible test case |
Teammates investigate concurrently. First to find strong evidence messages the team.
See debugging-team-prompt.md for spawn template.
Review Team
When: Thorough code review from multiple expert perspectives.
Composition (2-3 teammates):
| Role | Focus | Deliverable |
|---|
| Security Reviewer | Vulnerabilities, auth, injection | Security findings |
| Performance Reviewer | Bottlenecks, complexity, caching | Performance findings |
| Correctness Reviewer | Logic errors, edge cases, types | Correctness findings |
All teammates read the same code but from different lenses. Read-only — no edits.
See review-team-prompt.md for spawn template.
Key Constraints
- One team per session — can't create a second team or nest teams
- File ownership is sacred — concurrent edits cause cascading Edit failures
- Clean up when done — orphaned teams waste resources
- Rich spawn prompts — teammates have zero prior context
- 2-5 teammates — more causes diminishing returns and coordination overhead
teammateMode: "auto" — uses tmux panes when available, in-process otherwise
Integration with Other Skills
- /brainstorming → Use before team spawning to clarify the approach
- /writing-plans → Create the plan, then use a team to execute it
- /finishing-a-development-branch → After team work, use to prepare for merge
- /subagent-driven-development → For independent tasks without communication needs (lighter weight)
