What Brief Do You Give When Delegating to a Subagent?

Cursor subagents are specialists the parent Agent can hand work to. Each runs in its own context window, then returns a result to the parent. Use them to isolate noisy research, shell, or browser work, or to specialize verification and debugging. Grounded in Subagents.

This post covers only the delegation brief: what counts as success · what context to pack · how to receive results. It is a different axis from the agent context budget post (long-session progress summaries). That piece keeps the same thread / next session alive; this piece is one handoff packet to a child. No pricing, token counts, or window-size numbers.

What are the success criteria?

One-line answer: State in one or two sentences what the subagent must verify or produce to be “done”, plus out of scope. “Make it nice” is not a success criterion.

Per the docs, a subagent gets a prompt, works autonomously, and returns a final message. It does not see prior chat history, so without a done definition it will either over-scope or stop early.

Success checklist:

Item	Put here	Do not put here
Done when	Verifiable outputs (paths, tests passed, report sections)	“Good quality”, “take a look”
Out of scope	Paths not to touch, no merge/deploy, no secrets	Open-ended idea dumps
Evidence	Format the parent will check (log summary, fail list)	“Paste the entire dump into the reply” only
Mode hint	Foreground if sequential; background if long/independent	Pricing or model cost talk

Practical example (verification handoff):

## Goal
Verify that the auth flow marked “done” actually works.

## Done when
- Ran related tests or a minimal manual check
- Reported pass / fail / incomplete per item
- Claims without reproduction or tests are marked incomplete

## Out of scope
- New features, large refactors, secrets / prod credentials

The docs’ verifier pattern is this axis: do not trust “marked complete”—confirm implementation and tests, then report passed vs incomplete. A description like “Use after tasks are marked done…” strengthens automatic delegation.

Orchestration hint: Planner → Implementer → Verifier should pass structured outputs into the next brief. Nested delegation has product limits (docs: main and direct subagents can spawn children; deeper spawn is restricted). Prefer a flat parent → specialists tree when debugging handoffs.

What context should you include?

One-line answer: Subagents start clean. Do not assume parent history, prior decisions, or open tabs. Pack only the minimum facts for this handoff into the prompt (or custom agent body).

From Subagents: Subagents start with a clean context. The parent agent includes relevant information in the prompt since subagents don’t have access to prior conversation history.

Include / exclude:

Include	Why	Exclude
Goal + success criteria (above)	Child knows the end state	Full chat transcript
Key paths, symbols, ticket IDs	Shrinks search space	Whole unrelated repo map
1–3 locked decisions	Expensive choices stay fixed	Full experiment logs and discarded hypotheses
Constraints (readonly, banned paths, branch)	Safety and merge hygiene	Secret / token bodies
Output shape (path, section headers)	Easy for parent to merge	“Be creative; figure it out”

For custom agents (.cursor/agents/*.md), the description field is the routing signal. Prefer “Use when implementing OAuth” / “Use after tasks are marked done” over “helps with coding”. Keep the body short and single-purpose. Docs anti-patterns: 2,000-word prompts and dozens of vague helpers.

Built-in Explore / Bash / Browser exist because intermediate output is noisy. The same rule applies to human-written briefs: noise stays in the child window; the parent should get summary, paths, decisions.

When launching several editors in parallel, they share the parent checkout by default and can clobber each other. Per the docs, ask for isolation (worktree / own environment) in the brief when needed. The git-worktree agent post covers isolation mechanics; this post covers the handoff sentence.

Boundary vs context-budget in one line: a progress file is state that continues the ticket; a subagent brief is the slice of that state for this child. Do not paste the whole progress file—copy only the Goal / Paths / Blocked lines this slice needs.

How do you receive results?

One-line answer: The parent gets the subagent’s final message. Use foreground when the next step depends on the output; background for long independent or parallel work. Continue with resume by agent ID.

Modes:

Mode	Behavior	When
Foreground	Blocks until done; returns the result	Next step needs this output
Background	Returns immediately; runs independently	Long tasks or parallel streams

Receiving results in practice:

Fix the final-answer shape in the brief. e.g. ## Summary / ## Paths / ## Passed / ## Failed / ## Open so the parent can quote and merge.
Check background progress. Docs: background subagents write under ~/.cursor/subagents/. Parent or human can read those files.
Resume. Each run returns an agent ID. “Resume agent <id> and …” continues with preserved context—no need to rewrite a full brief for follow-up analysis.
On failure. The subagent returns an error status. Parent retries, resumes with more context, or re-delegates to another specialist.
Hooks / file artifacts. For consistent structured files, docs suggest hooks. In the brief: “Write reports/<slug>.md; final message only needs the path.”

Explicit invocation: /verifier …, /debugger …, or natural language (“Use the verifier subagent to …”). For parallel work, ask for several tasks in one message so Agent can issue multiple Task calls. Cloud handoff (/in-cloud, /autopilot) is a different axis (VM + branch while local stays free)—do not mix it with a local subagent brief without stating the isolation goal.

FAQ

How is this different from the context-budget summary post?

Context-budget keeps a long session alive with Goal / Done / Next / Blocked progress in the repo. This post is the handoff packet into a child context (success criteria, minimum facts, return shape).

When skills or slash commands instead?

Per the docs: use a subagent for context isolation, multi-step work, parallelism, or independent verification; use a skill/command for one-shot repeatable tasks (changelog, format). Do not invent a subagent for simple one-shots.

Where do custom agent files live?

Project: .cursor/agents/ (compat: .claude/agents/, .codex/agents/). User-global: ~/.cursor/agents/ and siblings. On name conflict, project and .cursor/ win. Commit them for the team.

Can a subagent spawn another subagent?

Docs allow nesting within limits (main and direct subagents can spawn; deeper spawn is restricted). Hooks, tool policy, or mode may block Task. Prefer flat parent → specialists for complex pipelines.

Sources

Subagents — isolated context, foreground/background, built-in and custom agents, resume, best practices