Agent Teams Guide

Agent Teams Guide

A comprehensive guide to using parallel sub-agents in Claude Code skills for faster, more thorough execution. Agent teams are the key architectural pattern that separates a good skill from a great one — they turn sequential bottlenecks into parallel pipelines.

Table of Contents

• What Are Agent Teams?
• When to Use Agent Teams
• Agent Team Patterns
• Model Selection
• Best Practices
• Anti-Patterns
• Creating Your Own Agent Team Skills
• Worked Example: /quality-report
• Performance Characteristics

What Are Agent Teams?

Agent teams are groups of parallel sub-agents launched via Claude Code's Task tool. Each agent runs independently in its own context window, processes a specific piece of work, and returns structured results. A coordinator (the main skill execution) then synthesises all agent results into a unified output.

The mechanism is straightforward: Claude Code's Task tool can launch multiple sub-agents simultaneously. Each sub-agent is a complete Claude instance with its own context, tools, and instructions. Sub-agents cannot communicate with each other — they only communicate with the coordinator through their return values.

flowchart TD
    A[User invokes /skill] --> B

    subgraph p1 ["Phase 1: Setup"]
        B["COORDINATOR<br>Gathers input, parses arguments,<br>reads files, prepares agent prompts"]
    end

    B --> C1
    B --> C2
    B --> CN

    subgraph p2 ["Phase 2: Parallel Execution"]
        C1["Agent 1 — Task tool<br>Own context window<br>Own tool access<br>Returns: structured data"]
        C2["Agent 2 — Task tool<br>Own context window<br>Own tool access<br>Returns: structured data"]
        CN["Agent N — Task tool<br>Own context window<br>Own tool access<br>Returns: structured data"]
    end

    C1 --> D
    C2 --> D
    CN --> D

    subgraph p3 ["Phase 3: Synthesis"]
        D["COORDINATOR<br>Collects all agent results,<br>synthesises unified output,<br>resolves conflicts"]
    end

    D --> E[Output to user]

Key properties of agent teams:

• Parallel execution — All agents in a phase launch simultaneously and run concurrently
• Isolated context — Each agent has its own context window; no shared state between agents
• Independent failure — If one agent fails, others continue; the coordinator handles missing results
• Structured returns — Each agent returns data in a defined format the coordinator can combine
• Tool access — Sub-agents can use Read, Grep, Glob, WebFetch, and other tools (but not MCP tools — see MCP Tool Limitation below)

When to Use Agent Teams

Not every skill needs agent teams. Use this decision matrix to determine whether parallel agents will improve your skill:

Rule of thumb: If the work can be split into 3+ independent chunks that each take 10+ seconds, agent teams will provide a meaningful speedup. Below that threshold, the overhead of launching agents may not be worth it.

Agent Team Patterns

Three orchestration patterns cover nearly all agent team use cases in this collection.

Pattern 1: Fan-Out/Fan-In

The most common pattern. Multiple agents analyse different dimensions of the same input in parallel, then the coordinator synthesises their results into a unified report.

flowchart TD
    C1["COORDINATOR<br>Prepares shared input"]

    C1 --> A1
    C1 --> A2
    C1 --> A3

    subgraph agents ["Parallel Agents — Sonnet"]
        A1["Agent 1: Technical Impact<br>Analyses tech angle<br>Returns: tech matrix with severity"]
        A2["Agent 2: Cost Analysis<br>Analyses financial angle<br>Returns: costs with breakdown"]
        A3["Agent 3: Risk Assessment<br>Analyses risk angle<br>Returns: risk register"]
    end

    A1 --> C2
    A2 --> C2
    A3 --> C2

    C2["COORDINATOR<br>Combines all dimensions<br>into unified report"]

Characteristics:

• 3-5 agents (more than 5 increases overhead without proportional benefit)
• All agents read the same input but analyse different dimensions
• Each agent returns a different data structure (risk register, cost table, etc.)
• The coordinator's synthesis phase is where the real value is — combining perspectives

Skills using Fan-Out/Fan-In:

Pattern 2: Batch Processing

Used when the same operation needs to run on many items. Items are divided into equal-sized batches and each batch is processed by an independent agent.

flowchart TD
    C1["COORDINATOR<br>Divides 100 notes into 5 batches"]

    C1 --> A1
    C1 --> A2
    C1 --> A3
    C1 --> A4
    C1 --> A5

    subgraph agents ["Parallel Batch Agents — Haiku"]
        A1["Agent 1<br>Notes 1–20<br>Tag each note"]
        A2["Agent 2<br>Notes 21–40<br>Tag each note"]
        A3["Agent 3<br>Notes 41–60<br>Tag each note"]
        A4["Agent 4<br>Notes 61–80<br>Tag each note"]
        A5["Agent 5<br>Notes 81–100<br>Tag each note"]
    end

    A1 --> C2
    A2 --> C2
    A3 --> C2
    A4 --> C2
    A5 --> C2

    C2["COORDINATOR<br>Combines all batch results<br>Deduplicates"]

Characteristics:

• N agents (scales with input size; typically 1 agent per 15-20 items)
• All agents run the same logic on different data
• Haiku model preferred (cost-effective for repetitive work)
• Coordinator merges results and deduplicates

Skills using Batch Processing:

Pattern 3: Triage + Selective Processing

A two-phase pattern for large lists where only some items are worth deep analysis. Phase 1 uses fast, cheap agents to score everything; Phase 2 uses more capable agents only on high-scoring items.

flowchart TD
    C1["COORDINATOR<br>Sends 20 videos to triage"]

    C1 --> T1
    C1 --> T2
    C1 --> TN

    subgraph triage ["Phase 1: Triage — Haiku"]
        T1["Triage Agent 1<br>Videos 1–7<br>Quick-score 1–10"]
        T2["Triage Agent 2<br>Videos 8–14<br>Quick-score 1–10"]
        TN["Triage Agent N<br>Videos 15–20<br>Quick-score 1–10"]
    end

    T1 --> F
    T2 --> F
    TN --> F

    F{"Filter: score ≥ 7<br>5 of 20 pass"}

    F --> D1
    F --> D2
    F --> D3

    subgraph deep ["Phase 2: Deep Processing — Sonnet"]
        D1["Deep Agent 1<br>Video A<br>Full transcript + analysis"]
        D2["Deep Agent 2<br>Video B<br>Full transcript + analysis"]
        D3["Deep Agent 3<br>Video C<br>Full transcript + analysis"]
    end

    D1 --> C2
    D2 --> C2
    D3 --> C2

    C2["COORDINATOR<br>Triage table + deep analyses<br>+ cross-theme synthesis"]

Characteristics:

• Two-phase execution (Phase 2 depends on Phase 1 results)
• Phase 1: Fast, cheap agents score everything (Haiku)
• Filter: Only items above a threshold proceed to Phase 2
• Phase 2: Capable agents deeply process the filtered set (Sonnet)
• Cost optimisation: If 20% of items are worth deep analysis, you save 80% of Sonnet costs

Skills using Triage + Selective:

Model Selection

Choosing the right model for each agent is critical for balancing cost, speed, and quality.

Model Comparison

When to Use Each Model as a Sub-Agent

Cost Examples

5-agent fan-out quality report (Sonnet agents):

• Each agent reads ~50 notes ≈ ~100k tokens input, ~20k tokens output
• 5 agents total: ~500k input + ~100k output
• Cost: (500k × $3/MTok) + (100k × $15/MTok) = $1.50 + $1.50 = ~$3.00

Batch tagging 100 notes (Haiku agents):

• 5 agents, 20 notes each ≈ ~30k tokens input, ~5k tokens output per agent
• 5 agents total: ~150k input + ~25k output
• Cost: (150k × $1/MTok) + (25k × $5/MTok) = $0.15 + $0.13 = ~$0.28

Triage 20 videos (Haiku triage + Sonnet deep):

• Phase 1: 3 Haiku agents ≈ ~60k input, ~10k output = $0.06 + $0.05 = $0.11
• Phase 2: 4 Sonnet agents (20% pass triage) ≈ ~200k input, ~40k output = $0.60 + $0.60 = $1.20
• Total: ~$1.31 (vs ~$6.50 if all 20 processed by Sonnet)

Best Practices

1. Limit to 3-5 Parallel Agents

More agents means more overhead (prompt construction, result parsing, synthesis complexity) without proportional benefit. Beyond 5 agents, the coordinator's synthesis phase becomes the bottleneck.

If you need to cover more than 5 dimensions, consider grouping related dimensions into a single agent (e.g., "security and compliance" rather than two separate agents).

2. Write Complete Agent Prompts (No Shared State)

Each agent runs in its own context window with no access to the coordinator's context or other agents' results. The agent prompt must contain everything the agent needs:

• Full task description — What to analyse and how
• Input data — File paths, search terms, or pre-fetched content
• Step-by-step instructions — Specific actions to take
• Return format — Exact structure of the expected output
• Quality criteria — What constitutes good vs poor output

# GOOD: Self-contained agent prompt
"Read all .md files in ADRs/. For each file, parse the YAML frontmatter
and check for these fields: type, title, created, status, deciders. Score
completeness as: (fields present / 5) × 100. Return a JSON array of
{ filename, score, missingFields[] }."

# BAD: Assumes shared context
"Check the ADR files for the fields we discussed earlier and score them."

3. Define Explicit Return Formats

Agents must return data in a format the coordinator can programmatically combine. Be specific about structure:

# GOOD: Explicit return format
Return: JSON array of objects:
  { filename: string, score: number (0-100), issues: string[] }

# GOOD: Markdown table format
Return: Markdown table with columns:
  | Filename | Score | Missing Fields | Recommendation |

# BAD: Vague return format
Return: A summary of what you found

4. Handle Agent Failures Gracefully

Agents can fail (timeout, context exhaustion, parsing errors). The coordinator should:

• Check whether each agent returned valid results
• Continue synthesis with available results if one agent fails
• Note which dimension is missing in the output
• Never crash the entire skill because one agent failed

# In the synthesis phase:
If any agent failed to return results:
1. Note the missing dimension in the report
2. Mark that section as "Analysis unavailable"
3. Reduce confidence in the overall score
4. Suggest re-running the skill for complete results

5. Keep Agents Focused on One Dimension

Each agent should own exactly one dimension of analysis. Splitting work cleanly ensures:

• No duplicate analysis (wasted cost)
• Clear responsibility (no ambiguity about which agent covers what)
• Easy debugging (test one agent at a time)
• Combinable results (each agent's output is a distinct piece of the puzzle)

# GOOD: One dimension per agent
Agent 1: Technical impact (systems, APIs, data)
Agent 2: Organisational impact (teams, skills, processes)
Agent 3: Financial impact (costs, savings, ROI)

# BAD: Overlapping dimensions
Agent 1: Technical and security analysis
Agent 2: Security and compliance analysis  ← overlaps with Agent 1
Agent 3: Cost and technical debt analysis  ← overlaps with Agent 1

Anti-Patterns

Common mistakes when designing agent team skills:

Creating Your Own Agent Team Skills

A five-step guide to building skills with parallel agents.

Step 1: Identify Parallel Dimensions

Ask: "Can I split this work into 3-5 independent chunks where each chunk doesn't need the others' results?"

Fan-out test: If you're analysing something from multiple angles (cost, risk, technical, organisational), each angle is a dimension.

Batch test: If you're applying the same operation to many items, you have a batch processing opportunity.

Triage test: If only some items in a large list are worth deep processing, you have a triage opportunity.

Step 2: Define Each Agent's Contract

For each agent, specify:

**Agent N: <Descriptive Name>** (<Model>)
Task: <One-sentence purpose — what question does this agent answer?>
- <Step 1 — specific, actionable instruction>
- <Step 2 — specific, actionable instruction>
- <Step 3 — specific, actionable instruction>
Return: <Exact data structure — fields, types, format>

Step 3: Design the Synthesis Phase

Plan how the coordinator will combine agent results:

1. What is the unified output format?
2. How are scores/metrics from different agents combined? (weighted average? matrix?)
3. What happens if one agent's findings contradict another's?
4. What happens if an agent fails to return results?

Step 4: Write the Skill File

Follow the standard skill template (see Skills Reference):

---
description: <one-line description>
model: sonnet
---

# /<skill-name>

<Purpose paragraph>

## When to Use This Skill
## Usage
## Instructions

### Phase 1: <Setup — gather input, prepare agent prompts>
### Phase 2: <Agent Team — define all agents>
### Phase 3: <Synthesise — combine results, generate output>

## Output Format
## Examples

Step 5: Test and Iterate

1. Test each agent independently — Run one agent at a time to verify it returns the expected format
2. Test the synthesis — Verify the coordinator correctly combines all agent outputs
3. Test failure handling — Simulate one agent failing and verify graceful degradation
4. Benchmark cost — Calculate actual token usage to confirm cost estimates
5. Compare against sequential — Verify the agent team actually provides a speedup vs sequential execution

Use the /skill-creator skill to generate the boilerplate for your agent team skill.

Worked Example: /quality-report

Let's walk through exactly how the /quality-report skill executes, from invocation to final output. This skill uses a 5-agent fan-out pattern to analyse vault quality across five dimensions.

Step 1: User Invokes the Skill

/quality-report --type ADR --top-issues 10

The user wants a quality report for all ADR notes, with the top 10 issues highlighted.

Step 2: Coordinator Parses Arguments and Inventories Files

The coordinator (main skill execution, running on Sonnet):

1. Parses arguments: type=ADR, topIssues=10
2. Scans the vault using Glob: ADRs/ADR - *.md
3. Finds 25 ADR files
4. Reads frontmatter from each to extract type, tags, and dates
5. Prepares a file list to pass to each agent

Step 3: Coordinator Launches 5 Agents in Parallel

The coordinator makes 5 simultaneous Task tool calls. Each agent receives:

• The list of 25 ADR file paths
• The specific analysis instructions for its dimension
• The expected return format

flowchart TD
    C["Coordinator (Sonnet)"]

    C --> A1["Agent 1<br>Readability Analyst"]
    C --> A2["Agent 2<br>Link Density Analyst"]
    C --> A3["Agent 3<br>Metadata Completeness"]
    C --> A4["Agent 4<br>Structure Completeness"]
    C --> A5["Agent 5<br>Freshness & Tags"]

Step 4: Agents Execute in Parallel

All 5 agents run simultaneously. Each:

1. Receives its prompt with the file list and instructions
2. Reads the 25 ADR files using the Read tool
3. Analyses its assigned dimension
4. Returns structured data in the specified format

This takes roughly the same wall-clock time as a single agent, despite doing 5× the analytical work.

Step 5: Coordinator Collects All Results

When all agents complete, the coordinator receives 5 structured result sets:

Agent 1 → 25 readability scores with grade levels
Agent 2 → 25 link density scores with orphan flags
Agent 3 → 25 metadata scores with missing field lists
Agent 4 → 25 structure scores with missing section lists
Agent 5 → 25 freshness scores with tag issues

Step 6: Coordinator Synthesises the Report

The coordinator now:

1. Joins data by filename — Combines all 5 scores per file into a single record
2. Calculates the weighted overall score per file:

   overall = readability×0.20 + linkDensity×0.25 + metadata×0.20 + structure×0.20 + freshness×0.15
   

3. Assigns grades — A (90+), B (80-89), C (70-79), D (60-69), F (<60)
4. Ranks by score — Identifies the bottom 10 (worst quality)
5. Calculates vault-wide averages — Overall score, per-dimension averages
6. Identifies cross-cutting issues — e.g., "15 of 25 ADRs are missing the summary field"
7. Generates recommendations — Prioritised by impact

Step 7: Output to User

The final report is presented as a structured Markdown document:

# Vault Quality Report

**Date:** 2026-02-11 | **Scope:** ADRs/ | **Notes Analysed:** 25

## Overall Score: 72/100 (Grade: C)

| Dimension      | Score | Weight | Weighted |
|----------------|-------|--------|----------|
| Readability    | 78    | 20%    | 15.6     |
| Link Density   | 65    | 25%    | 16.3     |
| Metadata       | 80    | 20%    | 16.0     |
| Structure      | 74    | 20%    | 14.8     |
| Freshness      | 60    | 15%    | 9.0      |
| **Overall**    |       | 100%   | **71.7** |

## Top 10 Issues (Prioritised)

| # | Note                           | Score | Grade | Primary Issue              |
|---|-------------------------------|-------|-------|---------------------------|
| 1 | ADR - Legacy API Gateway.md   | 38    | F     | Stale, no links, missing sections |
| 2 | ADR - Batch Processing.md     | 45    | F     | Orphaned, no summary      |
...

## Recommendations

1. **Quick wins:** Add `summary` to 15 ADRs (improves metadata score by ~12 points)
2. **Link building:** Connect 8 orphaned ADRs to projects and systems
3. **Structure:** Add missing "Alternatives Considered" to 6 ADRs

Performance Characteristics

Agent teams provide near-linear speedup for independent work. The table below shows measured characteristics for vault health operations:

Sequential vs Agent Team Execution

Notes:

• Speedup is sub-linear due to coordinator overhead (prompt construction, result parsing, synthesis)
• Batch processing scales better (more agents = more parallelism) than fan-out (fixed at 3-5 agents)
• Agent launch overhead is ~5-10 seconds per agent, amortised across the work
• At 2000+ notes, batch processing with 10+ agents approaches near-linear speedup
• These are estimates based on typical token counts; actual times vary with note size and complexity

Cost Scaling

Agent teams don't save cost — they save time. The total tokens processed are the same; they're just processed in parallel. The exception is the triage pattern, which saves both time and cost by filtering before deep processing.

MCP Tool Limitation

MCP tools (Notion, YouTube, Diagrams, and other MCP server integrations) are not available inside sub-agents launched via the Task tool. This is a platform limitation — the Task tool creates isolated agent instances without MCP server connections.

Workaround: The coordinator must call MCP tools before launching agents, then pass the fetched data as part of the agent prompt.

flowchart LR
    P1["Phase 1<br>Coordinator fetches<br>data via MCP"] --> P2["Phase 2<br>Passes fetched data<br>as context to agents"] --> P3["Phase 3<br>Sub-agents analyse<br>pre-fetched data"]

Further Reading

• Skills Reference — Quick-reference table of all 37 skills with agent team details
• Blog Post — The theory behind the diagramming skills (layout algorithms, graph drawing research)
• /skill-creator — Generate new skill files with agent team boilerplate