What is team sizing heuristics?

A guideline that maps task complexity to a recommended team size (Simple 1-2, Moderate 2-3, Complex 3-4, Very Complex 4-5) and notes that additional teammates increase coordination overhead.

Presets define a ready-made composition with a specific size, agent types, and default focus dimensions (e.g., security, architecture) to accelerate setup for common workflows.

How should I choose subagent_type?

Select based on tool needs: general-purpose for tasks requiring broad tool access (Read, Write, Edit, Bash), and Explore for research or code exploration with read-only tools. Additional types may exist beyond this doc.

team-composition-patterns

npx machina-cli add skill wshobson/agents/team-composition-patterns --openclaw

Files (1)

SKILL.md

5.9 KB

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

Source

git clone https://github.com/wshobson/agents/blob/main/plugins/agent-teams/skills/team-composition-patterns/SKILL.mdView on GitHub

Overview

Helps orchestrate multi-agent teams by applying sizing heuristics, ready-made presets, and agent-type choices. Use it to decide how many teammates to spawn, pick the right preset, and assign the appropriate subagent types for a task.

How This Skill Works

Evaluate task complexity against the sizing heuristics, then pick a matching preset (Review, Debug, Feature, Fullstack, Research, Security, Migration). Assign subagent_type per role (e.g., general-purpose for implementation, Explore for research) and launch the team, optionally configuring the display mode for the workspace.

When to Use It

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

Quick Start

Step 1: Assess task complexity and consult the Team Sizing Heuristics to pick a starting size.
Step 2: Choose the Preset Team that best fits the task (e.g., Review for multi-dimensional quality checks, Migration for big upgrades).
Step 3: Assign subagent_type to each role (e.g., general-purpose for implementation, Explore for research) and launch the team with the desired display mode.

Best Practices

Start with the smallest team that covers all required dimensions (per the sizing heuristics).
Match team size to task complexity: Simple (1-2), Moderate (2-3), Complex (3-4), Very Complex (4-5).
Use preset templates (Review, Debug, Feature, Fullstack, Research, Security, Migration) to accelerate setup.
Document roles, responsibilities, and default agent types for each preset.
Pilot new team compositions on low-risk tasks to measure coordination overhead before scaling up.

Example Use Cases

Review a code change with a 3-person Review Team to cover security, performance, and architecture perspectives.
Debug a bug with multiple plausible root causes using a Debug Team configured with several investigators.
Develop a new feature using a Feature Team with a lead and parallel implementers.
Coordinate frontend, backend, and tests with a Fullstack Team for end-to-end feature work.
Migrate a large codebase with a Migration Team to parallelize changes while ensuring correctness.

Frequently Asked Questions

Add this skill to your agents