Cursor subagents official docs and the missing contract

The Cursor subagents official docs tell you what the runtime can do. They will not tell you who owns the agent when it breaks, and that is the page your team has to write yourselves. A Cursor SDK agent is agent behavior turned into software: a runtime with permissions, tests, an owner, and a release path. Cursor, Anysphere's AI code editor, gives you the product surface. The contract is yours.

Here is the pattern I keep seeing. The demo works, the first production PR breaks something, and the room goes quiet when someone asks who owns the agent. The docs did not fail you. The operating contract you never wrote did.

Read the official docs, then stop expecting them to govern

The real references are the Cursor Agent, Rules, Skills, and MCP pages on cursor.com, plus the changelog. Most engineers land there from a changelog lookup or from hunting for the .cursor/agents directory where subagent definitions live.

Use those pages as product references. They describe what the runtime can do, not what your team will allow it to do. Community examples can suggest patterns, but they should not set your permission model. The rule that matters lives in your repo, next to the agent.

Write the contract before you write the agent

Start every internal SDK agent with a short, checklist-style contract. It gives reviewers a stable object to inspect, and it gives the team a polite way to say no to attractive but unsafe tool access. Paste this and fill it in.

# 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

The owner field is the load-bearing line. If the agent changes code, name an engineering owner. If it reads private docs, name a data owner. If it calls external tools through MCP, name a connector owner. An agent with no owner is an incident on a timer.

Build a harness before you grant more autonomy

A useful agent proves itself on fixtures before it touches daily work. The harness is cheap to build and it is the difference between a tool you trust and one you babysit.

The point of the permission test is to watch the agent try something forbidden and fail, on purpose, with a record. That is the test you want green before you widen access, not after.

Stage the release instead of shipping it cold

Do not drop an internal agent straight into daily engineering work. Walk it through gates and watch what humans have to fix at each one.

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. If that number is high, the agent is fast and untrustworthy, which is the worst combination.

One more guardrail: the SDK should 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. Permissions belong in MCP configuration, with the Model Context Protocol specification as the boundary language. The SDK should orchestrate known behavior, not hide a governance gap.

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 for what the runtime can do, then put the local contract in your repo. Community examples can suggest patterns, but they should not define your permission model or stand in for an owner.

• 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 an owner, release notes, and a rollback path. The first question to answer is not what it can build, but who answers for its behavior when it is wrong.

• What belongs in an internal agent contract?

  The contract names the agent, its owner, its allowed and forbidden paths, its allowed and forbidden tools, the proof commands it must pass, a release rule, and a rollback path. That gives reviewers a stable object to inspect and lets the team refuse attractive but unsafe tool access without an argument every time.

• How should a team release an internal SDK agent?

  Stage it. Run it against a fixture repo, then one low-risk branch, then require human edits on the first production PR, record what the human changed, and update the contract before widening access. Track how often reviewers had to reconstruct missing intent, because that number tells you whether the agent is ready or just fast.

• When is the SDK the wrong tool?

  The SDK is the wrong tool when the behavior already has a home. Rules belong in .mdc files, repeatable workflows belong in skills, and permissions belong in MCP configuration. Reach for the SDK to orchestrate behavior you have already defined, not to paper over rules you never wrote down.

Where to start

Write the contract for the agent you already have, then run one fixture test before you build a second agent. The team-side patterns connect through the subagents and skills topic hub.