Skip to content

Create a custom agent

Add your own agent to a coordinator run by defining it in .cursor/agents.yaml. This guide assumes you already understand the coordinator's wave-based workflow — if not, read Coordinator first.

Add the agent

  1. Open (or create) .cursor/agents.yaml at the repo root. (The path is overridable via the AGENTS_FILE environment variable.)

  2. Add an entry keyed by the agent name. A new name adds an agent; reusing a built-in name (engineer, reviewer, critic, tester, memory) overrides that built-in.

security-auditor:
  description: "Reviews changes for security issues."
  role: checker
  model: claude-4.6-opus-high-thinking
  passes: 2
  persona: |
    You are a security auditor. Inspect the changed files for injection,
    authz, and secrets-handling flaws.

    Always end with:
    DONE: <summary>
    FILES: <files inspected>
    RESULT: PASS|FAIL
  1. Restart the coordinator MCP server. agents.yaml is read once at server startup, so your new agent will not appear until you restart it in Cursor (Settings → MCP).

Restart is required

Editing agents.yaml has no effect on a running coordinator. After any change, restart the angelo-coordinator MCP server, then re-run agents(action="list") to confirm the agent is registered.

Set the role

The role field decides where the agent may sit in the task graph — the graph validator enforces it:

Role Meaning Placement rule
implementer Writes code. Declare writes for it in the graph.
planner Read-only design/analysis. Runs before implementers; must not depend on one.
checker Read-only verifier. Must have an implementer in its ancestry.
meta Bookkeeping (e.g. memory). Exempt from ancestry rules; can run anywhere.

An agent with no role is treated as a checker. Every graph needs at least one implementer or planner.

Ask how it fits

When a user asks for a new agent, confirm whether it edits files (implementer), verifies someone else's work (checker), or does standalone work (meta) before writing the YAML.

Inherit from a base agent with extends

Use extends to inherit any unset fields (persona, role, model, passes, description) from another agent. Per-field precedence is: the entry's own field > the base's field > built-in default.

senior-engineer:
  extends: engineer
  model: claude-4.6-opus-high-thinking

This keeps the built-in engineer persona and implementer role, changing only the model. The base can be a built-in, a capability-contributed agent, or another local agent (chains are followed).

Override model and passes

  • model — the default model for this agent. Resolution order at run time: task-level model > agent-level model (here) > the parent agent's model.

  • passes — self-refinement loops the agent runs within a single task. Precedence: per-task passes > this passes > the rigor profile > built-in default (1).

A partial override merges with the built-in — set only what differs:

engineer:
  model: gpt-5.5-medium

This keeps the built-in engineer persona, role, and passes, swapping only the model.

Verify

  1. Restart the coordinator MCP server.
  2. Run agents(action="list") — your agent should appear with its role.
  3. Fetch its full prompt with agents(action="get") to confirm the persona resolved as expected.

Reference

For the coordinator tool surface, see MCP tools → coordinator. For the rigor/passes model and how waves execute, see Coordinator.

Semantically related entries from the memory graph.