Cursor — Agents

File format

Markdown

Discovery paths

.cursor/agents, AGENTS.md

Global install path

~/.cursor/agents

Syllago install method

Symlink, Direct copy

Symlink support

Yes

Native frontmatter fields

name, description, model, readonly, is_background

Features

How each feature converts to syllago's canonical format. See format conversion for what these statuses mean.

Fields

Native frontmatter or config fields this provider exposes. The first column is the provider's own field name; the canonical key column links to syllago's cross-provider equivalent.

Provider field	Conversion	Canonical key	Summary
model	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	model_selection	model frontmatter field selects a specific model for the agent, overriding the session default.
is_background	Embedded Conversion type: Embedded No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more →	—	is_background: true marks the agent as eligible to run in Cursor's background agents queue for concurrent execution.
readonly	Embedded Conversion type: Embedded No canonical equivalent — appended as prose in a conversion notes block so nothing is silently lost. Learn more →	—	readonly: true restricts the agent to read-only tools so it cannot edit files or run mutating commands.

Other features

Behaviors, conventions, and capabilities that aren't tied to a single named field — things like path-based activation, discovery rules, and lifecycle behavior.

Feature	Conversion	Summary
agent_scopes	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Two scopes: project (.cursor/agents/) and user-global (~/.cursor/agents/).
definition_format	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Markdown files with YAML frontmatter in .cursor/agents/ (project) or ~/.cursor/agents/ (user); the frontmatter declares name, description, model, readonly, and is_background, and the Markdown body becomes the agent's system prompt.
invocation_patterns	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Custom agents are invoked through the Cursor IDE agent picker; background-enabled agents can also run concurrently via the background agents UI. Subagents can be spawned by other agents for parallel execution workstreams.
Markdown + YAML frontmatter agent files	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Custom agents are .md files with YAML frontmatter (name, description, model, readonly, is_background) and a Markdown system-prompt body.
Project and user-global agent scopes	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Custom agents live in .cursor/agents/ at the project root or ~/.cursor/agents/ for user-global scope, following the same layout as Cursor's other content types.
subagent_spawning	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	Since Cursor 2.5, subagents can launch child subagents to create a tree of coordinated work. Nested launches require Task tool access and can be restricted by hooks or tool policies.
tool_restrictions	Translated Conversion type: Translated Actively mapped to the target provider’s equivalent field during conversion. Learn more →	readonly frontmatter flag restricts an agent to read-only tools; fine-grained per-tool allow/deny lists are not documented.
Common subagent coordination patterns	Preserved Conversion type: Preserved Syntax survives conversion but the target provider may not interpret it. Learn more →	Cursor documents three recommended subagent patterns: verification agents (validate completed work), debugger agents (specialize in root cause analysis), and orchestrator patterns (coordinate multiple specialist subagents sequentially).
Built-in Explore, Bash, and Browser subagents	Not portable Conversion type: Not portable Unique to this provider — can’t be carried across providers. Learn more →	Cursor ships three built-in subagents (Explore, Bash, Browser) that are harness-provided and not overridable via files; only user-authored agents under .cursor/agents/ or ~/.cursor/agents/ are portable.

Sources

Source
https://cursor.com/docs/subagents