Task toolparallel subtasksorchestrator skillallowed-toolssynthesise results

Skills with Subagents

A skill does not have to do everything itself. With the Task tool enabled in allowed-tools, your skill becomes an orchestrator — it spawns parallel child Claude instances, each handling one subtask, then collects and synthesises their output.

What is a subagent?

In Claude Code, a subagent is a separate Claude instance that your orchestrating skill spawns to handle one specific piece of work. Each subagent:

🔁
Runs independently
Does not share memory with the orchestrator or other subagents
⚡
Runs in parallel
Multiple subagents work at the same time, saving wall-clock time
📬
Returns a result
Sends its output back to the orchestrator when done
🎯
Has a narrow focus
Given a single well-defined task, not the whole problem
ℹ️ Info: Subagents require Claude Code (the CLI tool). They do not work in claude.ai chat skills. The Task tool is only available in the agentic environment.

How it works

1
You invoke the skill
e.g. /research "React Server Components"
2
Orchestrator Claude reads SKILL.md
It sees allowed-tools: [Task] and your Steps instructions
3
Orchestrator spawns subagents in parallel
Subagent A
Official docs & specs
Subagent B
Community posts & blogs
Subagent C
Comparisons & alternatives
4
Results returned to orchestrator
All subagents complete; orchestrator receives their text output
5
Orchestrator synthesises and outputs
Combines findings into one structured report for you

The key ingredient: allowed-tools

By default, skills do not have access to any tools. To enable subagents, add Task to the allowed-tools list in the frontmatter. Add any other tools your subagents will need too.

❌ No subagent access
SKILL.md
---
name: research
description: Research a topic.
---

## Steps
1. Research the topic.
✅ Subagents enabled
SKILL.md
---
name: research
description: Research a topic.
allowed-tools:
  - Task
  - WebSearch
---

## Steps
1. Spawn subagents via the Task tool.

Example 1 — /research

A single command spawns three subagents in parallel — one per angle — then returns one synthesised report. Without subagents this would require three separate conversations.

SKILL.md
---
name: research
description: >
  Research a topic using three parallel subagents.
  Usage: /research <topic>
  Example: /research "React Server Components"
  Outputs a structured summary covering docs, community, and comparisons.
allowed-tools:
  - Task
  - WebSearch
---

## Role
You are a research coordinator. Delegate subtasks to subagents, then
synthesise their results into one clear report.

## Steps
1. Read the topic the user provides after the command.
2. Spawn three subagents in parallel using the Task tool:
   - Subagent A: Search official documentation and specs.
   - Subagent B: Search community discussions, blog posts, and tutorials.
   - Subagent C: Find comparisons with alternative approaches.
3. Wait for all three subagents to return.
4. Synthesise the results into one report.

## Output format
### Overview
One paragraph summary.

### Key findings
- Bullet per important finding (source: A/B/C)

### Comparisons
Short table if relevant.

### Recommended next step
One sentence.

## Constraints
- Do not add findings that subagents did not return.
- Keep the total output under 600 words.
$ /research "React Server Components"
◆ Spawning subagents...
├─ [A] Searching official docs & specs
├─ [B] Searching community posts & tutorials
└─ [C] Finding comparisons with alternatives
◆ Waiting for results...
[A] ✔ Returned 4 findings
[B] ✔ Returned 6 findings
[C] ✔ Returned 3 findings
◆ Synthesising...
### Overview
React Server Components (RSC) run on the server and stream HTML
to the client without shipping their JS bundle to the browser.
### Key findings
- RSC reduces client bundle size by up to 60% in typical apps [A]
- Async/await is supported directly inside server components [A]
- Community reports improved LCP on data-heavy pages [B]
- Compared to Remix: RSC is granular; Remix loaders are simpler [C]
### Recommended next step
Start with the Next.js App Router quickstart to try RSC locally.
✔ Done (3 subagents, ~8 s total)

Example 2 — /audit

Review every TypeScript file in a directory by spawning one dedicated subagent per file. Each subagent reads only its file and reports findings independently.

SKILL.md
---
name: audit
description: >
  Audit every TypeScript file in a directory for issues.
  Usage: /audit <directory>
  Example: /audit src/api
  Spawns one subagent per file; collects and ranks all findings.
allowed-tools:
  - Task
  - Read
  - Bash
---

## Context
- Date: $CURRENT_DATE
- Files: $(find ${directory} -name "*.ts" | head -20)

## Steps
1. Read the file list from context.
2. For each file, spawn a subagent with the Task tool:
   - Give the subagent the file path.
   - Ask it to list Critical, Warning, and Suggestion findings.
3. Collect all subagent results.
4. De-duplicate overlapping findings.
5. Rank by severity: Critical first.

## Output format
## Audit — ${directory}
For each file with findings:
  ### filename.ts
  - 🔴 Critical: description
  - 🟡 Warning: description
  - 🔵 Suggestion: description

## Summary
X critical, Y warnings, Z suggestions across N files.
claude.ai/claude-code · /audit src/api
◆ Spawned 4 subagents for: auth.ts · tokens.ts · middleware.ts · helpers.ts
Audit — src/api
auth.ts
🔴 Critical: jwt.verify does not check expiry — pass { ignoreExpiration: false }
🟡 Warning: process.env.SECRET is not guarded against undefined at startup
middleware.ts
🟡 Warning: rate-limiter applied after auth check — should be first
🔵 Suggestion: extract token extraction logic into a shared helper
helpers.ts · tokens.ts
No critical or warning findings.
Summary: 1 critical, 2 warnings, 1 suggestion across 4 files

Best practices

🎯
Give each subagent one job
A subagent with a narrow task returns more accurate results than one with a broad or vague instruction. Split large problems into clearly independent pieces.
🚫
Do not nest subagents
Keep the hierarchy to one level: orchestrator spawns subagents. Subagents spawning their own subagents creates unpredictable chains and high token usage.
📋
Only request tools subagents actually need
List only the tools required. If Subagent A only reads files, it does not need WebSearch. Unnecessary tool access increases risk and slows the run.
📦
Collect, then synthesise
The orchestrator's final Step should always be to combine subagent results. Without an explicit synthesis step, Claude may stop after listing raw outputs.
🔢
Keep subagent count reasonable
2–5 subagents is a sweet spot. More than 10 simultaneous subagents can hit rate limits and produces results that are hard to merge coherently.

When to use subagents vs a single skill

SituationUse subagents?Why
Multiple independent search queries✅ YesQueries have no dependency on each other; parallel is faster
Review N files independently✅ YesEach file is self-contained; one subagent per file is clean
Sequential steps (A depends on B)❌ NoSubagents cannot share state; orchestrate sequentially instead
One focused transformation task❌ NoA single Claude invocation is faster and simpler
Tasks needing shared memory❌ NoSubagents are isolated — use a single skill with context instead
Gathering data from multiple sources✅ YesEach source is independent; parallelism cuts total time significantly
💡 Tip: The simplest subagent skill you can write is a /research skill with 2–3 subagents. Start there, verify the output quality, and then apply the same pattern to your own use case.

What's Next

Sub-agents extend what a single skill can do. The final skills lesson shows you how to package and share your skills with your team.