Team Composition Patterns
Best practices for composing multi-agent teams, selecting team sizes, choosing agent types, and configuring display modes for Claude Code's Agent Teams feature.
When to Use This Skill
- Deciding how many teammates to spawn for a task
- Choosing between preset team configurations
- Selecting the right agent type (subagent_type) for each role
- Configuring teammate display modes (tmux, iTerm2, in-process)
- Building custom team compositions for non-standard workflows
Team Sizing Heuristics
| Complexity |
Team Size |
When to Use |
| Simple |
1-2 |
Single-dimension review, isolated bug, small feature |
| Moderate |
2-3 |
Multi-file changes, 2-3 concerns, medium features |
| Complex |
3-4 |
Cross-cutting concerns, large features, deep debugging |
| Very Complex |
4-5 |
Full-stack features, comprehensive reviews, systemic issues |
Rule of thumb: Start with the smallest team that covers all required dimensions. Adding teammates increases coordination overhead.
Preset Team Compositions
Review Team
- Size: 3 reviewers
- Agents: 3x
team-reviewer
- Default dimensions: security, performance, architecture
- Use when: Code changes need multi-dimensional quality assessment
Debug Team
- Size: 3 investigators
- Agents: 3x
team-debugger
- Default hypotheses: 3 competing hypotheses
- Use when: Bug has multiple plausible root causes
Feature Team
- Size: 3 (1 lead + 2 implementers)
- Agents: 1x
team-lead + 2x team-implementer
- Use when: Feature can be decomposed into parallel work streams
Fullstack Team
- Size: 4 (1 lead + 3 implementers)
- Agents: 1x
team-lead + 1x frontend team-implementer + 1x backend team-implementer + 1x test team-implementer
- Use when: Feature spans frontend, backend, and test layers
Research Team
- Size: 3 researchers
- Agents: 3x
general-purpose
- Default areas: Each assigned a different research question, module, or topic
- Capabilities: Codebase search (Grep, Glob, Read), web search (WebSearch, WebFetch)
- Use when: Need to understand a codebase, research libraries, compare approaches, or gather information from code and web sources in parallel
Security Team
- Size: 4 reviewers
- Agents: 4x
team-reviewer
- Default dimensions: OWASP/vulnerabilities, auth/access control, dependencies/supply chain, secrets/configuration
- Use when: Comprehensive security audit covering multiple attack surfaces
Migration Team
- Size: 4 (1 lead + 2 implementers + 1 reviewer)
- Agents: 1x
team-lead + 2x team-implementer + 1x team-reviewer
- Use when: Large codebase migration (framework upgrade, language port, API version bump) requiring parallel work with correctness verification
Agent Type Selection
When spawning teammates with the Task tool, choose subagent_type based on what tools the teammate needs:
| Agent Type |
Tools Available |
Use For |
general-purpose |
All tools (Read, Write, Edit, Bash, etc.) |
Implementation, debugging, any task requiring file changes |
Explore |
Read-only tools (Read, Grep, Glob) |
Research, code exploration, analysis |
Plan |
Read-only tools |
Architecture planning, task decomposition |
agent-teams:team-reviewer |
All tools |
Code review with structured findings |
agent-teams:team-debugger |
All tools |
Hypothesis-driven investigation |
agent-teams:team-implementer |
All tools |
Building features within file ownership boundaries |
agent-teams:team-lead |
All tools |
Team orchestration and coordination |
Key distinction: Read-only agents (Explore, Plan) cannot modify files. Never assign implementation tasks to read-only agents.
Display Mode Configuration
Configure in ~/.claude/settings.json:
{
"teammateMode": "tmux"
}
| Mode |
Behavior |
Best For |
"tmux" |
Each teammate in a tmux pane |
Development workflows, monitoring multiple agents |
"iterm2" |
Each teammate in an iTerm2 tab |
macOS users who prefer iTerm2 |
"in-process" |
All teammates in same process |
Simple tasks, CI/CD environments |
Custom Team Guidelines
When building custom teams:
- Every team needs a coordinator — Either designate a
team-lead or have the user coordinate directly
- Match roles to agent types — Use specialized agents (reviewer, debugger, implementer) when available
- Avoid duplicate roles — Two agents doing the same thing wastes resources
- Define boundaries upfront — Each teammate needs clear ownership of files or responsibilities
- Keep it small — 2-4 teammates is the sweet spot; 5+ requires significant coordination overhead
1---2name: team-composition-patterns3description: Design optimal agent team compositions with sizing heuristics, preset configurations, and agent type selection. Use this skill when deciding team size, selecting agent types, or configuring team presets for multi-agent workflows.4license: MIT5---6# Team Composition Patterns78Best practices for composing multi-agent teams, selecting team sizes, choosing agent types, and configuring display modes for Claude Code's Agent Teams feature.910## When to Use This Skill1112- Deciding how many teammates to spawn for a task13- Choosing between preset team configurations14- Selecting the right agent type (subagent_type) for each role15- Configuring teammate display modes (tmux, iTerm2, in-process)16- Building custom team compositions for non-standard workflows1718## Team Sizing Heuristics1920| Complexity | Team Size | When to Use |21| ------------ | --------- | ----------------------------------------------------------- |22| Simple | 1-2 | Single-dimension review, isolated bug, small feature |23| Moderate | 2-3 | Multi-file changes, 2-3 concerns, medium features |24| Complex | 3-4 | Cross-cutting concerns, large features, deep debugging |25| Very Complex | 4-5 | Full-stack features, comprehensive reviews, systemic issues |2627**Rule of thumb**: Start with the smallest team that covers all required dimensions. Adding teammates increases coordination overhead.2829## Preset Team Compositions3031### Review Team3233- **Size**: 3 reviewers34- **Agents**: 3x `team-reviewer`35- **Default dimensions**: security, performance, architecture36- **Use when**: Code changes need multi-dimensional quality assessment3738### Debug Team3940- **Size**: 3 investigators41- **Agents**: 3x `team-debugger`42- **Default hypotheses**: 3 competing hypotheses43- **Use when**: Bug has multiple plausible root causes4445### Feature Team4647- **Size**: 3 (1 lead + 2 implementers)48- **Agents**: 1x `team-lead` + 2x `team-implementer`49- **Use when**: Feature can be decomposed into parallel work streams5051### Fullstack Team5253- **Size**: 4 (1 lead + 3 implementers)54- **Agents**: 1x `team-lead` + 1x frontend `team-implementer` + 1x backend `team-implementer` + 1x test `team-implementer`55- **Use when**: Feature spans frontend, backend, and test layers5657### Research Team5859- **Size**: 3 researchers60- **Agents**: 3x `general-purpose`61- **Default areas**: Each assigned a different research question, module, or topic62- **Capabilities**: Codebase search (Grep, Glob, Read), web search (WebSearch, WebFetch)63- **Use when**: Need to understand a codebase, research libraries, compare approaches, or gather information from code and web sources in parallel6465### Security Team6667- **Size**: 4 reviewers68- **Agents**: 4x `team-reviewer`69- **Default dimensions**: OWASP/vulnerabilities, auth/access control, dependencies/supply chain, secrets/configuration70- **Use when**: Comprehensive security audit covering multiple attack surfaces7172### Migration Team7374- **Size**: 4 (1 lead + 2 implementers + 1 reviewer)75- **Agents**: 1x `team-lead` + 2x `team-implementer` + 1x `team-reviewer`76- **Use when**: Large codebase migration (framework upgrade, language port, API version bump) requiring parallel work with correctness verification7778## Agent Type Selection7980When spawning teammates with the Task tool, choose `subagent_type` based on what tools the teammate needs:8182| Agent Type | Tools Available | Use For |83| ------------------------------ | ----------------------------------------- | ---------------------------------------------------------- |84| `general-purpose` | All tools (Read, Write, Edit, Bash, etc.) | Implementation, debugging, any task requiring file changes |85| `Explore` | Read-only tools (Read, Grep, Glob) | Research, code exploration, analysis |86| `Plan` | Read-only tools | Architecture planning, task decomposition |87| `agent-teams:team-reviewer` | All tools | Code review with structured findings |88| `agent-teams:team-debugger` | All tools | Hypothesis-driven investigation |89| `agent-teams:team-implementer` | All tools | Building features within file ownership boundaries |90| `agent-teams:team-lead` | All tools | Team orchestration and coordination |9192**Key distinction**: Read-only agents (Explore, Plan) cannot modify files. Never assign implementation tasks to read-only agents.9394## Display Mode Configuration9596Configure in `~/.claude/settings.json`:9798```json99{100 "teammateMode": "tmux"101}102```103104| Mode | Behavior | Best For |105| -------------- | ------------------------------ | ------------------------------------------------- |106| `"tmux"` | Each teammate in a tmux pane | Development workflows, monitoring multiple agents |107| `"iterm2"` | Each teammate in an iTerm2 tab | macOS users who prefer iTerm2 |108| `"in-process"` | All teammates in same process | Simple tasks, CI/CD environments |109110## Custom Team Guidelines111112When building custom teams:1131141. **Every team needs a coordinator** — Either designate a `team-lead` or have the user coordinate directly1152. **Match roles to agent types** — Use specialized agents (reviewer, debugger, implementer) when available1163. **Avoid duplicate roles** — Two agents doing the same thing wastes resources1174. **Define boundaries upfront** — Each teammate needs clear ownership of files or responsibilities1185. **Keep it small** — 2-4 teammates is the sweet spot; 5+ requires significant coordination overhead
JantonioFC