Cursor Agent Conventions for Teams

This research library uses AI-assisted source research and drafting. Linked sources support product claims; analysis and proposed exercises are our interpretation. Unless an article documents a test and its results, do not read it as a hands-on review or an independently verified benchmark.

A Cursor agent should not start from a blank chat. For an engineering team, the useful setup is a small convention: what the agent may change, which Cursor rules and Cursor skills it should inherit, when to use subagents, and how a human reviews the diff. I use this framing in Cursor workshop sessions because it keeps agent work close to the repo instead of living in one developer’s prompt history.

Cursor agents are most useful when rules, skills, custom subagents, and MCP are treated as repo interfaces. Put durable constraints where Cursor can find them, keep task prompts short, and review outputs by file diff, test result, and assumption list. For the wider cluster of patterns, I keep related notes under Subagents and skills.

Choose the Cursor surface before prompting

As of October 2026, Cursor’s docs separate Agent, Rules, Skills, Subagents, Hooks, MCP, and Cloud Agents as distinct areas. That split is worth preserving in your team convention. Do not ask one prompt to carry architecture, task scope, external access, and review policy.

That table is deliberately boring. Boring is good here. It makes the first decision visible before anyone writes a clever prompt.

Keep repo rules small and local

Put rules where they match the code they constrain. A root rule can describe package management, test commands, and PR expectations. A local rule near a payment module can say that money values use integer cents and that rounding changes need an explicit test.

In a Next.js workflow, I would not write a general rule like “make good React components.” I would write a repo rule that says UI changes in packages/ui must keep public component props backward compatible unless the PR includes a migration note. That gives the agent a constraint a reviewer can actually check.

If your repo already has an AGENTS.md for broad agent instructions, do not duplicate every line into Cursor rules. Use AGENTS.md for shared team conventions and Cursor rules for the pieces you want Cursor to apply at the right scope.

Turn repeated work into skills and subagents

A Cursor skill should package a repeatable workflow, not a preference. Good candidates are “add an API endpoint with validation,” “write a migration with rollback notes,” or “update a design token and run the visual checks.” The skill should contain the commands and the shape of the expected result.

Use a Cursor subagent when the role itself repeats. A database migration reviewer can inspect schema changes, check generated SQL, and ask for rollback notes. It should not become a general backend owner.

MCP deserves the same discipline. If the agent needs GitHub, Jira, Figma, or an internal document store, expose the smallest useful surface first. In the Delegate and Review steps of our methodology, I want the team to see both the task given to the agent and the evidence used to accept or reject the result.

For a broader team operating model around Cursor, I would pair this convention with Cursor AI for Team Workflows, then keep this page focused on the agent handoff itself.

Copy this operating convention

Paste this into a repo doc such as docs/ai/cursor-agent-convention.md, then adapt the names to your project. Keep it short enough that it gets read during a PR.

# Cursor agent operating convention

## Default scope
- The agent works inside the issue, PR, or file boundary named in the prompt.
- The agent must list any file it wants to change outside that boundary before editing it.
- Large refactors, dependency upgrades, and data migrations need an explicit human approval step.

## Rules
- Root Cursor rules hold repo-wide commands, package manager choices, and PR expectations.
- Local Cursor rules hold module-specific constraints, such as API compatibility, data formats, or security checks.
- Rules are changed by PR and reviewed like code.

## Skills
- Create a Cursor skill when the same workflow has been prompted three times.
- A skill must include the commands to run, the expected output, and the common failure cases.
- A skill should not carry broad architecture policy that belongs in rules.

## Subagents and custom agents
- Create a subagent for a repeated specialist role, not for a one-off task.
- Each subagent has one owner, one job, and one review checklist.
- Retire a subagent if reviewers cannot tell whether it improved the work.

## MCP access
- New MCP servers start read-only unless the team approves a write path.
- External data used by the agent must be named in the PR notes.
- Secrets, production data, and customer records stay outside agent access unless the security review says otherwise.

## Review
- Every agent PR includes the prompt goal, changed files, tests run, and known uncertainties.
- The reviewer checks the diff, not the chat transcript alone.
- Failed tests must be explained before the PR is merged.

Adoption path: one engineer proposes the convention in a small PR, the module owners review the parts that affect their code, and the team lead decides where the file lives. After that, changes to rules, skills, subagents, and MCP access should move through the same PR path as code.

Review rule: no agent-generated PR is accepted because the answer sounded plausible. Accept it when the diff is small enough to inspect, the tests match the risk, and the agent’s assumptions are written down.

Further reading

• Cursor Agent docs
• Cursor rules
• Cursor skills

Start with one agent-safe change

Take one recurring PR chore, write the convention above, and run it on a small change before giving it background work. In hands-on training, this is the exercise I use to make Cursor delegation and review visible to the whole team.