majiayu000 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:
- Identify the full scope of what needs to be done
- Map dependencies — which tasks depend on others?
- Group independent tasks — these can run in parallel
- 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:
- Collect all subagent outputs (compact summaries only enter main context)
- Analyze findings for conflicts or gaps
- Synthesize into unified action plan
- Execute final decisions in main context (or delegate next batch)
Phase 5: Sequential Gates (if needed)
When later tasks depend on earlier results:
- Wait for Batch 1 subagents to complete
- Synthesize Batch 1 results
- Use synthesized results to inform Batch 2 prompts
- Launch Batch 2 subagents in parallel
- 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 |