Scope and Precedence: Where Subagents Live
Five Places a Subagent Can Live
Where you store a subagent file determines who can use it and how widely. There are five locations, and when two subagents share the same name, the higher-priority location wins. Knowing this ladder prevents confusing 'why is the wrong agent running?' surprises.
The precedence ladder: managed > CLI flag > project > user > plugin. Higher entries win when names collide.
Project vs. User: The Two You'll Use Most
| Project (.claude/agents/) | User (~/.claude/agents/) | |
|---|---|---|
| Available in | The current project only | All your projects |
| Shared with team | Yes — check into version control | No — personal to your machine |
| Best for | Codebase-specific reviewers, conventions | Personal workflow helpers |
| Priority | Higher (3) | Lower (4) |
Project subagents are team-shareable and codebase-specific; user subagents are personal and global.
Check project subagents into git
Project subagents (.claude/agents/) are ideal for agents specific to a codebase — a reviewer that knows your conventions, a test writer that follows your patterns. Commit them so your whole team uses and improves them collaboratively, like any other source file.
How Identity and Discovery Work
Claude Code scans .claude/agents/ and ~/.claude/agents/ recursively, so you can organize files into subfolders (agents/review/, agents/research/). But a subagent's identity comes ONLY from its name frontmatter field — the folder path doesn't affect how it's identified or invoked. Keep name values unique across the whole tree: if two files in one scope declare the same name, Claude Code keeps one and silently discards the other.
Two subtleties to remember
(1) Project subagents are discovered by walking UP from your working directory; directories added with --add-dir grant file access but are NOT scanned for subagents. (2) Plugin subagents are the exception to the folder rule: a subfolder becomes part of the scoped identifier (agents/review/security.md in 'my-plugin' → my-plugin:review:security).
The Other Sources
Beyond project and user files, three more sources round out the ladder:
- •Managed settings (highest) — deployed by org admins; takes precedence over project and user subagents with the same name.
- •--agents CLI flag — JSON passed at launch, session-only, not saved to disk; great for testing/automation.
- •Plugins (lowest) — installed subagents that appear in /agents alongside yours; for security, plugin subagents can't use hooks, mcpServers, or permissionMode fields.
Next
You know where subagents live. Next we go deep on the three choices that most shape a subagent's behavior: its model, its tools, and (lightly) its color.
Key Takeaways
- ✓Subagents can live in five locations; on a name conflict, the higher-priority location wins.
- ✓Precedence (high→low): managed settings (org) > --agents CLI flag (session) > project (.claude/agents/) > user (~/.claude/agents/) > plugin agents/.
- ✓Project subagents are team-shareable (check into git) and codebase-specific; user subagents are personal and available across all your projects.
- ✓Identity comes only from the 'name' field — subfolders are scanned recursively but don't change identity; keep names unique (duplicates are silently discarded).
- ✓Project subagents are discovered by walking up from the working dir; --add-dir directories are not scanned for subagents.
- ✓Plugin subagents are the exception: subfolders become part of a scoped identifier (my-plugin:review:security), and they can't use hooks/mcpServers/permissionMode.
Check Your Understanding
Test what you learned in this lesson.
Q1.When two subagents share the same name, which one is used?
Q2.Where should you put a code-specific reviewer that your whole team should share?
Q3.What determines a subagent's identity for invocation?
Q4.Which subagent source has the HIGHEST precedence?
Practice This Lesson