Cursor Custom Subagents — Where Do You Define Them?

A Cursor custom subagent is a specialist child agent defined as Markdown plus YAML frontmatter. When the parent Agent delegates, the child works in its own context window and returns a final message. The point is to keep noisy research, shell output, or independent verification out of the main thread.

This post covers three axes only: file location · when to delegate · what stays in the parent prompt. No pricing, plans, token quotas, affiliates, or invented reviews.

Grounded in Cursor’s official Subagents guide—behavior, paths, delegation, and frontmatter only.

Where do the files live?

One-line answer: Put project agents in .cursor/agents/ and user-wide agents in ~/.cursor/agents/ as .md files. On name conflicts, project wins; within a project, .cursor/ beats .claude/ / .codex/.

Type	Path	Scope
Project	.cursor/agents/	Current repo only
Project (compat)	.claude/agents/, .codex/agents/	Current repo only
User	~/.cursor/agents/	All projects for this user
User (compat)	~/.claude/agents/, ~/.codex/agents/	All projects for this user

Each file is YAML frontmatter plus a prompt body. Documented fields:

Field	Default	Role
name	filename	Display id (lowercase + hyphens)
description	—	Task-tool hint; what Agent reads to decide delegation
model	inherit	Same as parent, or a specific model ID
readonly	false	true restricts writes and state-changing shell
is_background	false	true runs without blocking the parent

Minimal verifier example:

---
name: verifier
description: Validates completed work. Use after tasks are marked done.
model: inherit
readonly: true
---

You are a skeptical validator. Verify claimed work actually works.
Run relevant checks. Report passed vs incomplete. Do not accept claims at face value.

Practical layout:

1. Commit shared roles (verifier, debugger) under .cursor/agents/.
2. Keep personal-only helpers in ~/.cursor/agents/.
3. Use unique names so project overrides do not surprise you.
4. Compat folders work, but prefer .cursor/agents/ as the single source for Cursor-first teams.

repo/
  .cursor/
    agents/
      verifier.md      ← project, shared via VCS
      debugger.md
~/.cursor/
  agents/
    my-notes-helper.md ← user-wide only

Docs tip: ask Agent to draft the file, then tighten description against real prompts. Vague lines like “helps with coding” give no routing signal.

When should you delegate?

One-line answer: Delegate when you need context isolation, parallel workstreams, or multi-step specialist verification. Keep one-shot work in the parent, a skill, or a command.

From the docs’ subagents-vs-skills table:

Hand to a subagent	Keep in parent / skill
Long research / codebase exploration (noisy intermediates)	One-shot changelog, import format
Multiple workstreams in parallel	A quick repeatable action
Multi-step expertise (security audit, deep debug)	No need for a separate context window
Independent verification of claimed work	Short edits the parent already understands

Built-ins (explore, bash, browser) exist because intermediate output would bloat the main context—Agent uses them automatically. Custom agents add team standards and named roles on top.

Trigger patterns:

1. Automatic: put “use proactively” / “always use for …” in description.
2. Explicit: /verifier …, /debugger …, or natural language (“use the verifier subagent…”).
3. Parallel: ask for parallel streams in one message so Agent can issue multiple Task calls.
4. Foreground vs background: default foreground when you need the result now; use is_background: true (or long background work) when you do not want to block.

Delegate when:
- Intermediate output is noisy (search, logs, browser DOM)
- You need a second opinion (verifier) with a fresh context
- Two+ independent streams can run at once

Do NOT spin a custom subagent for:
- One-shot format / rename / changelog
- Vague “helper” roles without a triggering description
- Duplicating a skill that does not need isolation

Anti-patterns from the docs: dozens of vague helpers, 2,000-word prompts, cloning skills that do not need isolation. Start with two or three focused roles.

What stays in the parent prompt?

One-line answer: Subagents do not see prior chat, so the parent must pack goal, scope, success checks, and paths into the handoff—and keep orchestration, merge, and user decisions on the parent side.

Docs: “Subagents start with a clean context. The parent agent includes relevant information in the prompt.”

Put in the child Task prompt	Keep on the parent
Done when / out of scope	Overall ticket goal and priority
Relevant paths, repro steps, error summary	Merging child results and resolving conflicts
Short pointer to role checklist already in the .md	Choices that need the user
Return shape (passed / failed / open questions)	Whether to resume (agent ID) or delegate next

Pin these lines in the parent session:

Parent keeps:
- Overall goal and acceptance for the user-facing change
- Which specialist to call (/verifier, /debugger) and in what order
- Merge policy: parent integrates diffs; subagents report only
- Do not assume subagents see prior chat — pass paths and criteria each time

Parent hands off in the Task prompt:
- Goal (one sentence)
- Touch / Do-not-touch paths
- Success checks (commands or observable outcomes)
- Return format (passed / failed / open questions)

Orchestrator pattern from the docs: Planner → Implementer → Verifier, with structured handoffs. Prefer readonly: true on verifiers so “fix while verifying” does not blur ownership.

Do not leave on the parent handoff:

• Pasting the entire role essay already stored in the child’s .md
• “Look around the whole repo” with no touch list
• Secrets, deploy approval, or merge authority the human/parent must hold

# Bad handoff
"Fix auth somehow."

# Better handoff (parent → verifier)
"Claimed done: OAuth callback in apps/web/src/auth/callback.ts.
Verify end-to-end: login → callback → session cookie.
Out of scope: redesign UI, touch apps/admin.
Return: passed checks, failed checks, incomplete items."

Frequently asked questions

Same name in project and user dirs?
Project wins. Inside one project, .cursor/ takes precedence over .claude/ / .codex/.

Does a good description guarantee auto-delegation?
Agent considers complexity, descriptions, and context. Phrases like “use proactively” help. For critical verification, still invoke with /name.

Can subagents spawn subagents?
Yes, within a nesting limit: the main agent and its direct subagents can spawn; deeper spawn is restricted. Hooks, tool policy, or mode may block Task. Prefer a flat parent → specialists tree for complex pipelines.

Should every tiny task get a custom agent?
No. Use skills/commands for one-shots without isolation needs; reserve custom agents for repeated specialist roles.

What should you remember?

Define agents under .cursor/agents/ (or ~/.cursor/agents/), delegate when you need isolation, parallelism, or independent verification, and keep goal / order / merge on the parent while shipping context in every child prompt. Source: Cursor Subagents. No pricing or affiliates.

Where are the official sources?

• Cursor — Subagents — locations, frontmatter, auto/explicit delegation, foreground/background, best practices
• Adjacent: subagent-brief (one-page handoff), cursor-skills-vs-rules (skills vs rules), agent-context-budget (same-session summary)