Skip to content
AgentAtlas

Cursor subagents: .cursor/agents, frontmatter, built-in Explore and Browser

How do I create and use subagents in Cursor?

Create a markdown file with YAML frontmatter in .cursor/agents/ for a project or ~/.cursor/agents/ for all your projects, then call it with /name in a prompt or let Agent delegate to it automatically. Cursor also ships built-in Explore and Browser subagents. Agent can run several subagents in parallel, each with its own clean context.

Where subagent files live

  • Project: .cursor/agents/, .claude/agents/ or .codex/agents/ (current project only).
  • User: ~/.cursor/agents/, ~/.claude/agents/ or ~/.codex/agents/ (all your projects).
  • Project subagents override user subagents with the same name.
  • If names clash across folders, .cursor/ wins over .claude/ and .codex/.

File format and frontmatter

.cursor/agents/verifier.md

---
name: verifier
description: Checks that completed work actually meets the request. Use proactively after finishing a feature.
model: inherit
readonly: true
---

You are a verifier. Confirm the requested change is complete.

1. Read the relevant files.
2. Run the tests.
3. Report anything missing.
  • name: lowercase letters and hyphens. Defaults to the filename.
  • description: the parent uses it to decide when to delegate.
  • model: inherit (default) or a model ID.
  • readonly (default false): true blocks file edits and state changing shell commands.
  • is_background (default false): true runs the subagent without blocking the parent.

Built-in subagents

  • Explore: searches and analyzes the codebase, using a faster model for parallel searches.
  • Browser: controls the browser and filters noisy DOM snapshots and screenshots.

Invoke a subagent

  • Explicit: type /name in your prompt, or name the subagent in plain language.
  • Automatic: Agent delegates based on the task and the subagent's description. Words like "use proactively" in the description encourage this.
  • Resume: each run returns an agent ID that you can pass back to continue that subagent.

Agent prompt

/verifier confirm the auth flow is complete

Parallel, background and isolated runs

  • Parallel: Agent can start multiple subagents in one message so they run at the same time.
  • Background subagents return right away and write state to ~/.cursor/subagents/.
  • By default, subagents share the parent's checkout. A subagent can instead get its own Git worktree or its own cloud VM.
  • Each subagent uses its own tokens, so five parallel subagents cost about five times as much as one.
  • A subagent started by another subagent cannot start more subagents.

Sources

More Cursor guides

Reviewed Oct 18, 2026. Settings change often; the linked vendor docs are the source of truth.

Built an MCP server? Get it listed everywhere →

Shipping an Android app? Google Play needs 12 testers for 14 days first. Get them with Tester Exchange →