Subagent Teams

Maintain optimum Claude performance by delegating heavy work to subagent teams, minimizing auto-compact of the main context window.

What This Skill Does

• Decomposes complex tasks into independent subtasks for parallel execution
• Delegates exploration, research, testing, and implementation to specialized subagents
• Keeps main orchestrator context lean (decision-making and synthesis only)
• Prevents auto-compact by isolating heavy work in separate context windows
• Selects optimal model per subtask (Opus for complex, Sonnet for moderate, Haiku for simple)

What This Skill Does NOT Do

• Handle tasks with strict sequential dependencies (use normal flow)
• Replace the main orchestrator's decision-making role
• Work for single-step trivial tasks (no delegation needed)
• Manage persistent state across subagent sessions

---

Before Implementation

Gather context to ensure successful delegation:

Source	Gather
User Request	Full scope of the task, constraints, preferences
Codebase	Project structure, key files, existing patterns
Skill References	Delegation patterns from references/
Task Complexity	Number of independent subtasks, dependencies between them

Only ask user for THEIR specific requirements (delegation strategy is in this skill).

---

Core Principle: Context Isolation

WITHOUT subagent-teams:
  Main Context: [Explore + Search + Read + Analyze + Plan + Implement + Test]
  Result: Context fills → Auto-compact triggers → Quality degrades

WITH subagent-teams:
  Main Context: [Decompose → Delegate → Synthesize → Decide]
  Subagent 1: [Explore codebase] → returns summary
  Subagent 2: [Run tests] → returns pass/fail
  Subagent 3: [Implement feature] → returns code
  Result: Main context stays lean → No auto-compact → Consistent quality

---

Workflow

Phase 1: Task Decomposition

Analyze the user's request and break it into independent subtasks:

1. Identify the full scope of what needs to be done
2. Map dependencies — which tasks depend on others?
3. Group independent tasks — these can run in parallel
4. Identify sequential gates — tasks that must complete before others start

User Request
     │
     ▼
┌─────────────────────────┐
│ Dependency Analysis      │
│ - Independent tasks → parallel batch
│ - Dependent tasks → sequential order
│ - Gates → sync points  │
└─────────────────────────┘
     │
     ▼
[Parallel Batch 1] → [Gate] → [Parallel Batch 2] → [Gate] → [Final Synthesis]

Phase 2: Team Assignment

For each subtask, select the optimal subagent configuration:

Subtask Type	subagent_type	Model	Tools
Codebase exploration	Explore	haiku	Read, Grep, Glob
Architecture design	Plan	sonnet	All read tools
Multi-step implementation	general-purpose	sonnet/opus	All tools
Simple file search	Explore	haiku	Glob, Grep
Code review	Explore	sonnet	Read, Grep
Test execution	general-purpose	haiku	Bash, Read

Phase 3: Parallel Dispatch

Launch independent subagents in a single message with multiple Task tool calls:

# CORRECT: Single message, multiple tool calls (parallel)
Message contains:
  - Task tool call 1: Explore agent for codebase research
  - Task tool call 2: Explore agent for pattern analysis
  - Task tool call 3: General-purpose agent for test execution

# WRONG: Sequential messages (wastes time)
Message 1: Task tool call 1
[wait for result]
Message 2: Task tool call 2
[wait for result]

Phase 4: Result Synthesis

After subagents return:

1. Collect all subagent outputs (compact summaries only enter main context)
2. Analyze findings for conflicts or gaps
3. Synthesize into unified action plan
4. Execute final decisions in main context (or delegate next batch)

Phase 5: Sequential Gates (if needed)

When later tasks depend on earlier results:

1. Wait for Batch 1 subagents to complete
2. Synthesize Batch 1 results
3. Use synthesized results to inform Batch 2 prompts
4. Launch Batch 2 subagents in parallel
5. Repeat until task is complete

---

Delegation Decision Matrix

Condition	Action
Task has 3+ independent subtasks	Use subagent-teams
Context window already large	Delegate ALL exploration
Task involves multiple file reads	Delegate to Explore agents
Task requires testing + implementation	Separate into different agents
Task is single-step and simple	Do NOT delegate (overhead not worth it)
Tasks have strict sequential dependency	Use sequential gates, not parallel
User explicitly requests subagent-teams	Always apply this skill

---

Subagent Prompt Engineering

Write clear, focused prompts for each subagent:

Must Include

• Specific goal: What exactly to find/do/produce
• Scope boundary: What files/areas to focus on
• Output format: How to structure the response
• Context: Relevant information from earlier steps

Must NOT Include

• Unnecessary background (wastes subagent context)
• Multiple unrelated tasks in one agent (breaks specialization)
• Vague instructions ("look around the codebase")

Template

"[Action verb] [specific target] in [scope].
Focus on [key aspects].
Return: [structured output format].
Context: [relevant prior findings if any]."

---

Anti-Patterns

Anti-Pattern	Why It's Bad	Correct Approach
Reading 10+ files in main context	Fills context → auto-compact	Delegate to Explore agent
Long grep/search chains in main	Each result adds to context	Single Explore agent does all searching
Explore AND implement in same session	Double context usage	Explore agents first, then implement
One mega-agent for everything	No specialization, bloated context	Multiple focused agents
Not using run_in_background	Blocks main session	Use background for long tasks
Asking subagent for info you already have	Wastes subagent context	Pass known context in prompt

---

Model Selection Strategy

Task Complexity	Model	Cost	Use When
Simple search/grep	haiku	Low	Finding files, simple patterns
Moderate analysis	sonnet	Medium	Code review, architecture design
Complex reasoning	opus	High	Multi-step implementation, critical decisions
Default (unspecified)	inherits	-	When unsure, let it inherit

---

Error Handling

Scenario	Recovery
Subagent returns incomplete results	Re-launch with more specific prompt
Subagent times out	Check with AgentOutputTool, adjust scope
Conflicting results from agents	Synthesize manually, prioritize authoritative source
Too many parallel agents	Limit to 3-5 concurrent, batch the rest
Background agent still running	Use AgentOutputTool with block=false to check status

---

Output Checklist

Before completing a subagent-teams workflow, verify:

• All subtasks identified and categorized (independent vs dependent)
• Subagent types correctly matched to task types
• Independent tasks launched in parallel (single message)
• Sequential gates properly handled
• Results synthesized into coherent output
• Main context remains lean (no unnecessary file reads)
• Model selection optimized for cost/performance

---

Reference Files

File	When to Read
references/delegation-patterns.md	Complex task decomposition examples
references/prompt-templates.md	Subagent prompt engineering patterns
references/context-management.md	Context window optimization strategies