A subagent is a second agent your main agent can hand a task to. It starts with a clean context, its own instructions, its own list of allowed tools and, optionally, a different model. When it finishes, only its final answer comes back. Everything it read along the way stays out of your main conversation.
That last point is the real benefit. Context is the scarcest resource in a long agent session. A subagent lets you spend it on the work that matters.
Defining a subagent
Both Claude Code and Cursor use a Markdown file with YAML frontmatter. In Claude Code, project agents live in .claude/agents/, user agents in ~/.claude/agents/. Cursor reads .cursor/agents/, .claude/agents/ and .codex/agents/.
---
name: scout
description: Read-only repo explorer. Use to find the files, functions and tests relevant to a change before editing anything.
tools: Read, Grep, Glob
model: haiku
---
You are a scout. You never edit files.
1. Find the files and symbols relevant to the task you are given.
2. Return at most 15 bullet points: path, symbol, one-line reason.
3. End with the single file the main agent should open first.| Field | What it does |
|---|---|
name | How you and the main agent refer to it |
description | When the main agent should delegate to it; written like a skill description |
tools | The tools it may use. Leave out to inherit all; list them to restrict |
model | haiku, sonnet, opus, a full model ID, or inherit |
The body is the subagent's system prompt. It never sees your main conversation, so it must be self-contained.
Three signals a task should be delegated
- It produces far more input than output. Searching a codebase, reading logs, scanning 40 PRs. The subagent reads 50,000 tokens and returns 500.
- It needs a different permission level. A read-only reviewer should not be able to edit. Restricting
toolsmakes that a property of the agent, not a hope. - It suits a cheaper or different model. Summaries, proofreading and classification rarely need your most capable model.
If none of those apply, keep the work in the main chat. Delegation has a cost: the subagent has to rediscover context you already have, and you lose the step-by-step view of what it did.
Writing a brief the subagent can act on
The main agent writes a brief each time it delegates. You can shape that brief through the subagent's description and body. A good brief has:
- The goal in one sentence: "Find where order totals are calculated."
- Scope: "Only under
src/billing/. Ignore tests." - Output contract: "Return paths and line numbers, max 15 bullets."
- A stop rule: "If you find more than 3 candidate implementations, stop and list them."
The output contract matters most. A subagent without one tends to return an essay, and the essay lands in the context you were trying to protect.
Step by step: your first delegation
- Create
.claude/agents/scout.mdwith the file above. - Restart your host or open a new chat.
- Ask: "Use the scout agent to find where we parse environment variables."
- In Claude Code,
/agentslists available agents; the run shows as a separate task in the transcript. In Cursor the agent appears as a Task tool call. - Check the result follows the contract (15 bullets max, a "start here" file). If it rambles, tighten the body's output section.
Patterns that work
| Pattern | Subagent | Why |
|---|---|---|
| Scout then build | Read-only scout on a small model | Main agent starts the edit with a precise file list |
| Independent review | reviewer with Read/Grep only | Fresh eyes: it did not write the code it is checking |
| Parallel fan-out | Several scouts, one per package | Large monorepos; results merged by the main agent |
| Proofreading | proofreader that may edit docs only | Cheap model, narrow tools |
When subagents make things worse
- Tiny tasks. Spawning a subagent to read one file costs more than reading it.
- Tasks that need the conversation history. The subagent cannot see what you and the main agent decided ten turns ago unless the brief repeats it.
- Chains of subagents. Each hop loses detail. Two levels is usually the useful limit.
Quick check
-
What does the main conversation receive from a subagent?Only its final answer. The files and tool output it read stay in the subagent's own context.
-
You want a reviewer that can never edit code. How?Restrict its
toolsto read/search tools such as Read, Grep and Glob. -
Name the part of a brief that most protects your main context.The output contract: a strict limit on what comes back and in what shape.






