[DOCS] Clarify recursive subdirectory discovery in ~/.claude/agents/ and .claude/agents/

Summary

Files inside subdirectories of ~/.claude/agents/ are discovered as subagents (e.g. ~/.claude/agents/foo/bar.md with name: bar becomes the bar subagent). The docs at code.claude.com do not appear to address whether this is intended behavior. Requesting an explicit statement so users can rely on (or avoid) the behavior when planning their agents/ directory structure.

Reproduction

mkdir -p ~/.claude/agents/_subdir_test
cat > ~/.claude/agents/_subdir_test/probe.md <<'PROBE'
---
name: subdir-discovery-probe
description: Probe to verify subdirectory scanning under ~/.claude/agents/
---

Probe body.
PROBE

cd /tmp
claude -p "List every subagent type available to you. Output names only, newline-separated."

In the listing returned, subdir-discovery-probe appears alongside top-level subagents.

Where the docs are silent

I checked the following pages and could not find a statement on whether subdirectories of agents/ are recursively scanned:

• /en/sub-agents — describes scopes (.claude/agents/, ~/.claude/agents/, plugin agents/) and project-discovery walking up from cwd, but does not address recursion into an agents/ folder.
• /en/plugins-reference#plugin-directory-structure — the canonical "Plugin directory structure" example shows agents/ as flat-only top-level .md files, in contrast to skills/ which is explicitly shown as nested <name>/SKILL.md.
• /en/plugins — defers to plugins-reference for organization.
• /en/agents — overview comparison, no directory-structure detail.
• /en/agent-sdk/subagents — SDK side, no recursion discussion.

The frontmatter table at /en/sub-agents notes "The filename does not have to match" the name: field, but does not address path.

There are open feature requests for recursive skills/ discovery (#18192, #20805), but no equivalent thread for agents/.

Request

Please clarify in the docs (most naturally at /en/sub-agents under "Choose the subagent scope" or in /en/plugins-reference#plugin-directory-structure):

1. Whether subdirectories inside ~/.claude/agents/, .claude/agents/, and plugin agents/ are recursively scanned for subagent .md files.
2. If yes, whether the path affects the subagent's identity in any way. In my test the name: frontmatter is the sole identifier; paths do not namespace.
3. If yes, what happens when two files in different subdirectories share the same name: value.
4. If no, the expected behavior of files placed in subdirectories.

Why this matters

Users planning a long-term agents/ taxonomy need to know whether they can organize files into subfolders (e.g. agents/research/, agents/review/) or must keep a flat layout with filename prefixes. The behavior works but is undocumented, which makes it an unsafe foundation for anyone maintaining many subagent definitions and wanting to commit to a structure.

Environment

• Claude Code: 2.1.141
• OS: macOS 26.4.1 (Darwin 25.4.0)
• Reproduced on: user-scope ~/.claude/agents/