[DOCS] plugins-reference still shows a flat `agents/` tree and omits recursive scanning and path-scoped identifiers

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/plugins-reference

Section/Topic

"Standard plugin layout" tree and the "Agents" component section

Current Documentation

The layout tree shows agents/ as flat top-level files only (verified 2026-09-16):

├── agents/                   # Subagent definitions
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md

The "Agents" section says only:

Location: agents/ directory in plugin root

The page contains no occurrence of "recursive", "subfolder", or "subdirectory" in the context of agents/.

What's Wrong or Missing?

/en/sub-agents documents two behaviors that /en/plugins-reference does not mention:

Claude Code scans .claude/agents/ and ~/.claude/agents/ recursively, so you can organize definitions into subfolders such as agents/review/ or agents/research/.

Plugin agents/ directories are also scanned recursively. Unlike project and user scopes, a subfolder inside a plugin's agents/ directory becomes part of the scoped identifier: a file at agents/review/security.md in plugin my-plugin registers as my-plugin:review:security.

The reference page is the page a plugin author reads to learn the layout. That page shows agents/ flat, while it shows skills/ nested. A reader concludes that subfolders under agents/ are unsupported. The path-scoped identifier rule also changes how a user invokes the agent, and the reference page never states it.

Suggested Improvement

Two small edits:

1. Add one nested example to the layout tree:

├── agents/                   # Subagent definitions (scanned recursively)
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── review/
│       └── compliance-checker.md   # registers as my-plugin:review:compliance-checker

1. Add one paragraph to the "Agents" component section, after the Location line:

Claude Code scans the agents/ directory recursively. A subfolder becomes part of the scoped identifier: agents/review/security.md in plugin my-plugin registers as my-plugin:review:security. See [Organize subagents in subdirectories](/docs/en/sub-agents) for the project and user scope rules.

Impact

Medium - Makes feature difficult to understand

Additional Context

Lineage: #58950 first asked for this clarification and the stale bot closed it. #68046 refiled the remaining plugins-reference gap on 2026-06-12, and the stale bot closed it on 2026-09-14 with no maintainer reply. The bot's closing note asks for a new issue when the topic is still relevant, so this is that issue.

The gap is unchanged since #68046. One maintainer reply that confirms the sub-agents wording is the intended contract resolves this issue.