Cursor subagents and skills for teams

Cursor subagents and skills work well on a team repo when their boundaries live in plain, explicit files instead of in someone's head. A subagent scope is the set of paths one delegated Cursor agent is allowed to edit during a single PR. Cursor, Anysphere's AI code editor, gives you subagents that run in parallel and skills that package reusable instructions, and both get confusing fast once more than one person ships against them. The fix is boring on purpose: write the scopes down so a reviewer can name which file governed a diff.

This piece is for the person who just spent twenty minutes asking "which skill made it do that?" and got no clean answer.

Put scopes in files, not in your memory

The most common failure on a shared repo is that nobody can say which rule or skill governed a given change. Two sources of truth activate at once, and precedence becomes trivia.

So make it citable. Split your rules by folder concern instead of shipping one mega-glob .mdc that claims **/*. When everything is active, nothing is trusted, and a reviewer has to guess. A narrow glob lets them point at the exact file that was in charge.

Then give each skill a preamble. Open every SKILL.md by naming the .mdc rules that override it. Now the deferral is written down before the next diff needs it, instead of being rediscovered in review.

Stop parallel subagents from editing the same code

Spawn a few subagents and sooner or later two of them edit the same module, and you reconcile the duplicate by hand. List mutex paths in AGENTS.md: the directories where only one subagent may run per PR.

A visible git conflict is the cheaper failure here. It surfaces the collision the moment it happens rather than hiding it inside a clean-looking merge.

Here is a small delegation snapshot you can adapt. Keep the globs honest to your own layout.

---
description: Delegation boundary snapshot (adapt globs to your repo)
globs:
  - "**/*"
alwaysApply: false
---

- Cursor: keep scopes explicit in `.mdc`; forbid undeclared MCP domains.
- Claude Code: cite `CLAUDE.md` precedence before expanding bash scope.
- Codex: ensure `AGENTS.md` carries replay-friendly verification notes for CLI runs.

Give temporary prompts a retire-by date

Demo prompts ship fast and then quietly become the default, because nobody owns removing them. Prefix any risky prompt with an owner and a retire-by date inside the rule comments.

That single line turns cleanup into something scheduled instead of heroic. When the date passes, anyone can delete the prompt without a meeting, because the comment already said who put it there and why it was temporary.

Check the PR against a short receipt

Before you trust an agent's diff, run it through a few plain questions. The goal is a short auditable trail, not ceremony.

Paste this checklist into the PR template so it travels with every change:

• Verification command output is pasted or linked.
• Forked agent work lists parent + child responsibilities.
• Mutex-path directories received explicit human acknowledgement.
• Scopes in the PR body match folders in the diff.

If your repo cannot state its boundaries plainly, agents will guess, and guessing scales poorly.

Common questions

• How do Cursor subagents work on a team repo?

  Cursor subagents work on a team repo when their scopes live in explicit files. Split .mdc rules by folder concern, open each SKILL.md with a preamble naming what overrides it, and list mutex paths in AGENTS.md so only one subagent runs per PR in a given directory. The parent agent keeps the merge; the files keep the boundaries.

• How do you stop parallel subagent edits from colliding?

  List mutex paths in AGENTS.md: the directories where only one subagent may run per PR. Without that list, parallel runs duplicate edits in the same module and someone reconciles them by hand later. With it, a git conflict surfaces the collision right away, which is the cheaper and louder failure to deal with.

• Which wins when a Cursor skill contradicts a rule?

  Whatever the repo wrote down wins, which is the entire point of the skill preamble. Every SKILL.md opens by naming the .mdc files that override it. Precedence fights keep recurring because two sources of truth activate without a merge ritual, so record the deferral once and stop relitigating it in review.

• Do I need AGENTS.md if I already have rules files?

  Yes, because they answer different questions. Rules files say how an agent should behave inside a folder; AGENTS.md says which folders a subagent is even allowed to touch this PR. You can run subagents without it, but the first parallel collision you clean up by hand will make the case for adding it.

Start with one module

Pick one module and run its scopes through our training drill: one repo, one subagent, one receipt format the team will keep. The cluster overview lives at Cursor subagents and skills if you want the wider map first.