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:

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:

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

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

Model Selection Strategy

Error Handling

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