ysskrishna logoysskrishna

Chapter 4 of 9 · 4 min

Subagents: when to split the work

What a subagent is, how to define one in Claude Code and Cursor, and the three signals that a task should be delegated.

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.
FieldWhat it does
nameHow you and the main agent refer to it
descriptionWhen the main agent should delegate to it; written like a skill description
toolsThe tools it may use. Leave out to inherit all; list them to restrict
modelhaiku, 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

  1. It produces far more input than output. Searching a codebase, reading logs, scanning 40 PRs. The subagent reads 50,000 tokens and returns 500.
  2. It needs a different permission level. A read-only reviewer should not be able to edit. Restricting tools makes that a property of the agent, not a hope.
  3. 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

  1. Create .claude/agents/scout.md with the file above.
  2. Restart your host or open a new chat.
  3. Ask: "Use the scout agent to find where we parse environment variables."
  4. In Claude Code, /agents lists available agents; the run shows as a separate task in the transcript. In Cursor the agent appears as a Task tool call.
  5. 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

PatternSubagentWhy
Scout then buildRead-only scout on a small modelMain agent starts the edit with a precise file list
Independent reviewreviewer with Read/Grep onlyFresh eyes: it did not write the code it is checking
Parallel fan-outSeveral scouts, one per packageLarge monorepos; results merged by the main agent
Proofreadingproofreader that may edit docs onlyCheap 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

  1. 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.

  2. You want a reviewer that can never edit code. How?Restrict its tools to read/search tools such as Read, Grep and Glob.

  3. 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.

Continue exploring

Productnpm+3Thinking Methods

Thinking Methods

17 well-known thinking methods your AI coding assistant can actually run.
Agent Skills
AI Apps & Assistants
Bash
Gemini
BlogCover image for 17 Thinking Skills for AI Agents: Pre-Mortem, Five Whys, Six Hats and More

17 Thinking Skills for AI Agents: Pre-Mortem, Five Whys, Six Hats and More

AI Apps & Assistants
Agent Skills
4 min read
ToolCover image for AI Token Counter

AI Token Counter

AI token counter with model pricing and context-window comparison in your browser.

Chat & AI
AI Apps & Assistants
+1
Productskills.sh+1Claude Code Subagents for Cursor

Claude Code Subagents for Cursor

Your Cursor subagents can finally run on the model you picked in each agent file.
Chat & AI
Agent Skills
AI Apps & Assistants
Bash
CourseCover image for Prompt Engineering for Coding Agents

Prompt Engineering for Coding Agents

Write prompts that coding agents act on: clear goals, the right context, output contracts, examples, structured thinking, shorter answers and a tiny eval set.

Agent Skills
Chat & AI

8 chapters · 21 min

BlogCover image for How to Install Caveman in Cursor and Claude Code

How to Install Caveman in Cursor and Claude Code

AI Apps & Assistants
Agent Skills
+1
3 min read