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
- How to allow Cursor to run all commands: Run Everything, allowlist and sandbox
- Cursor Privacy Mode: telemetry, training and data retention
- Add MCP servers to Cursor with mcp.json
- Keep files out of Cursor with .cursorignore
- Cursor CLI: install, headless mode, permissions and CI
- Cursor hooks: hooks.json, beforeShellExecution, afterFileEdit and exit codes
- Cursor sandbox: sandbox.json, network allowlist and run modes
- Cursor settings: settings.json, Cursor Settings and the ~/.cursor config files
- Cursor browser agent: @browser, browser automation and approval modes
- Cursor telemetry and OpenTelemetry export (Privacy Mode, OTLP, Analytics API)
- Cursor rules setup: project, user and Team Rules, .mdc frontmatter, globs and AGENTS.md
- Cursor skills and custom slash commands: .cursor/skills SKILL.md, .cursor/commands and /migrate-to-skills
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 →