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.
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.
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.
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/agent/overview