🇺🇸English
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 |
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
Weekly Installs
2.4K
Repository
wshobson/agents
GitHub Stars
32.3K
First Seen
Feb 5, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykWarn
Installed on
gemini-cli2.0K
opencode1.9K
codex1.9K
claude-code1.9K
cursor1.8K
github-copilot1.8K
