Cursor

Cursor subagents: .cursor/agents, frontmatter, built-in Explore, Bash 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, Bash 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.
  • Bash: runs a series of shell commands and keeps verbose output out of the main chat.
  • 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

Cursor: SubagentsCursor: Changelog 2.4

More on Cursor

Cursor standards supportAdd MCP servers to CursorCursor rules

Other guides

Cursor: allow all terminal commandsClaude Code: allow commands without promptsCodex CLI: approval and sandbox modesGemini CLI: YOLO mode, auto_edit and allowing specific shell commandsCursor Privacy Mode: telemetry, training and data retentionClaude Code telemetry and data retention: what is sent and how to turn it offGemini CLI: turn off usage statistics and telemetryCLAUDE.md: where it goes, how it loads, and how it works with AGENTS.mdClaude Code hooks: format on save, block risky edits, get notifiedClaude Code subagents: create one, limit its tools, and call itAdd MCP servers to Cursor with mcp.json: Keep files out of Cursor with .cursorignore: Configure Codex with config.toml: Configure Gemini CLI with settings.json: Add MCP servers to Claude Code (claude mcp add, .mcp.json, scopes): Claude Code custom slash commands and skills (SKILL.md): GitHub Copilot custom instructions: Adding MCP servers to GitHub Copilot: Claude Code settings.json: file locations, precedence, and key settingsClaude Code plugins and marketplaces: install, create, and shareGemini CLI extensions and custom commands: Configuring OpenCode with opencode.json: Cline Rules: workspace, global, and conditional rulesKiro steering files: .kiro/steering, inclusion modes, and AGENTS.mdZed agent: instruction files, MCP servers, tool permissions, and ACP agentsCursor CLI: install, headless mode, permissions and CIAider: CONVENTIONS.md, .aider.conf.yml and API keysJunie guidelines, MCP and the Action Allowlist: Amp AGENTS.md, settings.json and MCP: Configure Goose extensions, hints, recipes and permissions: Customize OpenHands with skills, AGENTS.md, setup.sh and MCP: Configure Factory Droid CLI: AGENTS.md, settings.json, autonomy, custom droids and MCPConfigure Qwen Code: settings.json, providers, QWEN.md, MCP and approval modesCursor hooks: hooks.json, beforeShellExecution, afterFileEdit and exit codesCursor sandbox: sandbox.json, network allowlist and run modesCursor settings: settings.json, Cursor Settings and the ~/.cursor config filesCursor browser agent: @browser, browser automation and approval modesCursor telemetry and OpenTelemetry export (Privacy Mode, OTLP, Analytics API): Cursor rules setup: .cursor/rules, .mdc frontmatter, globs, alwaysApply and AGENTS.md

Get the weekly agent stack update

New official MCP servers, spec changes and harness releases, checked against the source. One email a week, no fluff.

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