A project defines a subagent named `reviewer` in both `.cursor/agents/` and `.claude/agents/`, and edits to the file under `.claude/agents/` make no difference to how the subagent behaves. What explains that?

The principle — Cursor does not load subagents from a single folder. Project subagents come from .cursor/agents/, .claude/agents/ and .codex/agents/, with the matching three directories under the home folder supplying user subagents. Because several files can therefore claim the same name, Cursor resolves the clash by a fixed precedence: project beats user, and within a level the .cursor/ file beats the compatibility folders.

Why the key is correct — Both files are read and both are candidates for the name reviewer, but only one definition can win. The .cursor/ copy takes precedence, so its prompt, model and tool settings are the ones in force. Editing the shadowed copy edits a file nobody runs, which is exactly why the behaviour never changes.

Why the others are wrong — Treating the compatibility directories as inert is the belief the whole trap depends on; files left behind by another tool are loaded, which is what allows one to be shadowed in the first place. Definitions are also not stitched together field by field, so the losing file contributes nothing at all rather than contributing part of the configuration. And the duplicate is not kept under a separate identifier: the name resolves once, and the loser is simply invisible.

Remember this — When the same subagent name exists twice, the .cursor/ copy is the one that runs.

Sources — Cursor's Subagents documentation.