Cursor subagents official docs and the missing contract

The demo worked, the first production PR broke, and the room went quiet when someone asked who owned the agent. We went looking through the Cursor subagents official docs for the page that answers that question. That page does not exist, and it should not: ownership is your contract to write, not the vendor's. A Cursor SDK agent is agent behavior turned into software, a runtime with permissions, tests, owners, and a release path, and software without an owner is an incident on a timer.

The question behind the search

Counter-thesis: The docs are not what is missing; the operating contract your team never wrote is.

The wrong path: We believed the first working demo meant the agent was nearly done. We shipped it into real engineering work, and the demo turned out to have an author while the agent had no owner.

Diagnosis: This is the XY problem. Teams ask how to script the agent, the X, when the real question is who answers for its behavior, the Y. Every search for cursor agent sdk documentation returns surface answers to the wrong question.

Thesis: Treat an internal SDK agent as an internal product: contract first, harness second, autonomy last.

What the official docs do cover

The Cursor subagents official docs are the Cursor Agent, Rules, Skills, and MCP pages, plus the changelog. Engineers arrive there from changelog lookups (Cursor 3.6, auto-review) and from searches for the .cursor/agents directory where subagent definitions live; the cursor agent sdk docs describe what the runtime can do. Use them as product references, then put the local contract in the repo. Community examples can suggest patterns, but they should not define your permission model.

Contract first

Named fix: the agent contract. Start every internal SDK agent with a checklist-style contract:

# Internal Cursor SDK agent contract

- Agent name: dependency-upgrade-scout
- Owner: platform team
- Allowed paths: `package.json`, `pnpm-lock.yaml`, `apps/site/**`
- Forbidden paths: `infra/**`, `.github/workflows/**`
- Allowed tools: repository search, package metadata lookup
- Forbidden tools: deployment, secret reads, database writes
- Required proof: `pnpm install --lockfile-only` and `pnpm test dependency-upgrade`
- Release rule: first three runs require senior reviewer approval
- Rollback: revert agent PR; no direct push to main

If the agent changes code, the contract names an engineering owner; if it reads private docs, a data owner; if it calls external tools through MCP, a connector owner. Reviewers get a stable object to inspect, and the team gets a polite way to refuse attractive but unsafe tool access.

Harness second

Named fix: harness before autonomy. A useful SDK agent proves itself on fixtures before it touches daily work:

This is the Test step in our methodology: not only code correctness, but whether the workflow can be trusted when the operator is tired. The team-side patterns connect through the subagents and skills topic hub.

Autonomy last

Named fix: the staged release. Do not ship an internal agent straight into daily engineering work:

1. Run it against a fixture repo.
2. Run it against one low-risk branch.
3. Require human edits on the first production PR.
4. Record what the human changed.
5. Update the contract before widening access.

The metric that matters is not how much code the agent wrote. It is how often reviewers had to reconstruct missing intent.

Named fix: the layer check. The SDK must not become a workaround for missing repo rules. If a rule belongs in .mdc, put it there; if the behavior is a repeatable workflow, write the SKILL.md. The same goes for a cursor sdk skill: if it can be a skill, it does not need to be software. Permissions belong in MCP configuration with the Model Context Protocol specification as the boundary language. The SDK should orchestrate known behavior, not hide governance gaps; the single-run version of this discipline is the scope ledger in Cursor subagents and skills for engineering teams.

Synthesis: If you cannot name the owner, the permissions, and the rollback in one breath, the agent is a liability with good output.

Best ways to use this research

• Best for: Cursor teams deciding which rule, subagent, skill, or MCP boundary to standardize next around an internal SDK agent.
• Best first artifact: turn the agent contract into a .mdc rule, AGENTS.md note, or review checklist before the next automated run.
• Best comparison angle: compare the workflow against the current Cursor review path, connector scope, and team rule file; keep the path that leaves the shortest auditable trail.

Common questions

• Where are the Cursor subagents official docs?

  The official references are the Cursor Agent, Rules, Skills, and MCP pages on cursor.com, plus the changelog. Use them as product references, then put the local contract in the repo; community examples can suggest patterns, but they should not define your permission model.

• What is a Cursor SDK agent?

  A Cursor SDK agent is agent behavior turned into software: an internal product with a runtime, permissions, tests, and users. Treat it like software, with tests, owners, release notes, and a rollback path, because the first question is who owns its behavior when it is wrong.

• What belongs in an internal Cursor agent contract?

  The contract names the agent, its owner, allowed and forbidden paths, allowed and forbidden tools, required proof commands, a release rule, and a rollback path. That gives reviewers a stable object to inspect and lets the team say no to attractive but unsafe tool access.

• How should a team release an internal SDK agent?

  Stage it instead of shipping it straight into daily work: run it against a fixture repo, then one low-risk branch, require human edits on the first production PR, record what the human changed, and update the contract before widening access. The metric that matters is how often reviewers had to reconstruct missing intent.

• When is the SDK the wrong tool?

  The Cursor SDK is the wrong tool when the behavior belongs in an existing layer: rules belong in .mdc files, repeatable workflows belong in skills, and permissions belong in MCP configuration. The SDK should orchestrate known behavior, not hide governance gaps.

Next move

Write the contract for the agent you already have and run one fixture test before building a second one. The full governance argument behind contracts like this is in our white paper.