[DOCS] Align plugins-reference with sub-agents on recursive agents/ discovery

Summary

#58950 asked the docs to clarify recursive subdirectory discovery in agents/ directories. It received triage labels (documentation, enhancement, area:agents) but no human reply, and the stale bot closed it as not planned on 2026-06-12. Since it was filed, /en/sub-agents shipped most of the requested clarification (thank you). This issue covers what remains: a docs inconsistency on the plugins side, and the closure state of #58950 itself.

What shipped

/en/sub-agents now states (verified 2026-06-12):

Claude Code scans .claude/agents/ and ~/.claude/agents/ recursively, so you can organize definitions into subfolders such as agents/review/ or agents/research/. The subdirectory path does not affect how a subagent is identified or invoked, because identity comes only from the name frontmatter field. Keep name values unique across the whole tree: if two files within one scope declare the same name, Claude Code keeps one and discards the other without warning. 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.

This answers questions 1 through 3 of #58950 for all three scopes, and moots question 4.

What's still inconsistent

/en/plugins-reference has not caught up with the above:

• The "Standard plugin layout" tree still shows agents/ as flat-only top-level .md files (security-reviewer.md, performance-tester.md, compliance-checker.md), in contrast to skills/, which is shown nested. This is the exact contrast #58950 flagged as the source of ambiguity.
• The page contains no mention of recursive agents/ scanning or the path-scoped identifier behavior (my-plugin:review:security) that /en/sub-agents now documents. A plugin author reading only the reference page will conclude subfolders are unsupported.

Request: update /en/plugins-reference (the layout tree and/or the Agents component section) to reflect recursive discovery and the scoped-identifier rule, or cross-link to the sub-agents paragraph.

The record on #58950

#58950 is closed as not planned while the behavior it asked about is documented and supported. Anyone finding that issue via search gets exactly the wrong signal.

Request: a maintainer reopen #58950 and re-close it as completed, or comment there confirming the docs language is the intended contract.

Process note

#58950 was not declined by a maintainer; it was swept by the stale bot after 29 days without a human reply, despite carrying triage labels. The bot's closing message invites a new issue when the topic is still relevant, so this is that issue, filed in good faith per those instructions. A one-line maintainer reply here (even "the docs language is the intended contract, closing as completed") fully resolves the matter.

Longer term, please consider exempting issues that carry triage labels from the stale sweep, so triaged reports keep their labels, context, and discussion history.

Related tickets

| Issue | Status | Relevance |
| --- | --- | --- |
| #58950 | Closed as not planned (stale bot, 2026-06-12; zero human comments) | Original request for this clarification |
| #18192 | Open | Sibling request: recursive skills/ discovery |
| #20805 | Closed as not planned | Sibling request: recursive skills/ discovery for skill collections |