When Should You Use Subagents in Cursor?
Use a subagent when a piece of work is noisy, can run in parallel, or needs an independent check. Each runs in its own context window and returns only its result to the main chat. Agent uses built-in ones automatically, and you can define your own as markdown files in .cursor/agents/.
Create .cursor/agents/verifier.md with YAML frontmatter (name, description, readonly: true) and its instructions below that. This subagent checks finished work: confirm the feature actually runs, run [test command], and report what passed and what's incomplete. Its description should say to use it after a feature is reported as finished.
- 10Parallel Explore searchesin the time of one main-agent search
- 5xTokens for five subagentsroughly, against a single agent
- Noisy workoutput stays out of the main chat
- Parallel workseveral tasks at once
- Independent checksclean context, no stake in the code
Try it now
- 1Send the prompt above, then open the new file in
.cursor/agents/and read it. - 2Finish a small task, then say "use the verifier subagent to check this".
- 3Look for the subagent's Task card in the chat. It worked if a separate run reports its results and the main thread contains only the summary.
Use it when
Long research, several workstreams at once such as docs and API changes, or a reviewer that should check finished work. Type /multitask to have Cursor run async subagents in parallel instead of queuing your requests.
Skip it when
A simple, single-purpose job like generating a changelog or formatting imports. Cursor's docs recommend a skill for that. Also skip them when the task depends on earlier conversation, because a subagent doesn't see that history, only what the parent puts in its prompt.
Why it works
Searching dozens of files or reading browser snapshots produces a lot of output you don't need to keep. In a subagent, that output stays there, and the parent sees only the summary. Cursor's docs say its built-in Explore subagent uses a faster model, running 10 parallel searches in the time one main-agent search would take. Because each subagent starts with a clean context, it also has no stake in the code being reviewed, which is why the docs suggest them for independent verification.
Example
Say you ask "use a subagent to find all the places we validate user input". Explore searches many files and returns a list with paths, while your main chat stays small. You then ask for a security-auditor review, defined in .cursor/agents/security-auditor.md with readonly: true and a description saying to use it for auth and payment code. It reads your diff without any memory of how the code was written.
Going further
Subagents can spend money you don't see. Cursor's docs say each has its own token usage, so five in parallel use roughly five times the tokens of one agent. A subagent can also run a named third-party model while your picker still shows Auto, Grok or Composer, and those requests bill as third-party usage from prepaid credit. Check the model field: inherit is the default. You can set options such as model: claude-opus-5[effort=high]. To run one on its own VM and branch, type /in-cloud. Files in .claude/agents/ and .codex/agents/ load as well, with .cursor/ winning name conflicts.
Common mistakes
- Assuming a subagent knows the conversation. Put what it needs in its description or ask the parent to pass it along.
- A vague
description. Agent reads it to decide when to delegate. - Giving a review subagent write access. Set
readonly: true. - Being surprised by credit use because a custom subagent names a third-party model.
Sources
- Subagents, Cursor Docs
- Search, Cursor Docs
- What is multi-agent coding?, Cursor Help
- Usage and limits, Cursor Help
- Available models, Cursor Help
Checked 6 November 2026. Products change often, so confirm details with the vendor.