[DOCS] Nested `.claude/` agents, workflows, and output styles: closest-to-CWD collision rule and project-workflow save target are undocumented

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/sub-agents

Section/Topic

• sub-agents.md — "Project subagents" / "Choose the subagent scope" section (recursive scan paragraph)
• workflows.md — "Save the workflow for reuse" section (save dialog locations)
• output-styles.md — "Create a custom output style" → "Create a Markdown file" step (storage locations)

Current Documentation

From sub-agents.md (the only mention of how project .claude/agents/ is discovered today):

Project subagents (.claude/agents/) are ideal for subagents specific to a codebase. Check them into version control so your team can use and improve them collaboratively. Project subagents are discovered by walking up from the current working directory. Directories added with --add-dir grant file access only and are not scanned for subagents. To share subagents across projects, use ~/.claude/agents/ or a plugin. 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.

From workflows.md (project-scope save behavior):

Run /workflows, select the run you want to keep, and press s. In the save dialog, Tab toggles between the two save locations: .claude/workflows/ in your project: shared with everyone who clones the repo ~/.claude/workflows/ in your home directory: available in every project, visible only to you Press Enter to save. The workflow runs as /<name> in future sessions from either location. If a project workflow and a personal workflow share a name, the project one runs.

From output-styles.md (storage locations):

User: ~/.claude/output-styles Project: .claude/output-styles * Managed policy: .claude/output-styles inside the managed settings directory

What's Wrong or Missing?

The v2.1.178 changelog introduced a new resolution rule for nested .claude/ directories that is not described on any of the three affected documentation pages:

"Nested .claude/ directories: the agent, workflow, and output-style closest to the working directory now wins when names collide; project-scope workflow saves now target the closest existing .claude/workflows/"

A. sub-agents.md describes the wrong rule for cross-directory collisions

The current paragraph says the recursive scan keeps a same-named file and "discards the other without warning." That statement only addresses collisions within one .claude/agents/ tree. In a monorepo with multiple .claude/agents/ directories (for example, ./.claude/agents/reviewer.md and ./packages/web/.claude/agents/reviewer.md), v2.1.178 now resolves the collision in favor of whichever .claude/agents/ is closest to the working directory. None of this is mentioned. The phrase "walking up from the current working directory" hints at a parent-walk, but it is never tied to a collision-resolution rule, so a reader has no way to predict which of two same-named agents will load.

B. workflows.md is missing the nested save-target rule

The save-dialog section documents only the two flat locations (.claude/workflows/ in the project, ~/.claude/workflows/ in the home directory). v2.1.178 changes where "project-scope" saves land in a monorepo: the saver now targets the closest existing .claude/workflows/ to the current working directory, not necessarily the repo root. The save section needs to spell that out, and the collision paragraph ("If a project workflow and a personal workflow share a name, the project one runs.") needs a parallel statement for two project-scope workflows with the same name at different depths.

C. output-styles.md is missing the same nested-collision rule

The three-bullet storage list (User / Project / Managed) says nothing about nested .claude/output-styles/ directories. A monorepo with ./.claude/output-styles/reviewer.md and ./packages/web/.claude/output-styles/reviewer.md is now governed by the "closest wins" rule, but the page does not say so. By contrast, skills.md was updated in the same release to document the parallel "Automatic discovery from parent and nested directories" behavior, so the gap is specifically on the agents / workflows / output-styles pages.

D. Inconsistent depth with the skills page

skills.md already documents nested-skill discovery, including a name-clash convention (<dir>:<name>) introduced in v2.1.178. The agents / workflows / output-styles docs do not adopt the equivalent nested-walk language, so a reader who learns the skills model will not find the matching behavior described for the other three.

Suggested Improvement

sub-agents.md — extend the "Project subagents" / "Choose the subagent scope" section

Add a new paragraph after the "walking up" sentence that documents the new closest-wins rule, and revise the final warning sentence to be scoped to within-tree collisions only.

Before:

Project subagents are discovered by walking up from the current working directory. Directories added with --add-dir grant file access only and are not scanned for subagents. To share subagents across projects, use ~/.claude/agents/ or a plugin. 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.

After:

Project subagents are discovered by walking up from the current working directory. Directories added with --add-dir grant file access only and are not scanned for subagents. To share subagents across projects, use ~/.claude/agents/ or a plugin. 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. In a monorepo with multiple .claude/agents/ directories at different depths, the one closest to the current working directory wins when two files share a name. Keep name values unique within a single .claude/agents/ tree: if two files in the same directory declare the same name, Claude Code keeps one and discards the other without warning.

workflows.md — extend "Save the workflow for reuse"

Before:

In the save dialog, Tab toggles between the two save locations: .claude/workflows/ in your project: shared with everyone who clones the repo ~/.claude/workflows/ in your home directory: available in every project, visible only to you Press Enter to save. The workflow runs as /<name> in future sessions from either location. If a project workflow and a personal workflow share a name, the project one runs.

After:

In the save dialog, Tab toggles between the two save locations: .claude/workflows/ in your project: shared with everyone who clones the repo ~/.claude/workflows/ in your home directory: available in every project, visible only to you Press Enter to save. The workflow runs as /<name> in future sessions from either location. In a project with multiple .claude/workflows/ directories (for example, at the repo root and inside a package), the project-scope save targets the .claude/workflows/ directory closest to the current working directory, not necessarily the repo root. If a project workflow and a personal workflow share a name, the project one runs. If two project workflows at different depths share a name, the one closest to the current working directory wins.

output-styles.md — extend the "Create a Markdown file" step

Before:

User: ~/.claude/output-styles Project: .claude/output-styles * Managed policy: .claude/output-styles inside the managed settings directory

After:

User: ~/.claude/output-styles Project: .claude/output-styles * Managed policy: .claude/output-styles inside the managed settings directory In a project with multiple .claude/output-styles/ directories at different depths, the directory closest to the current working directory wins when two styles share a name. This mirrors the behavior of nested .claude/skills/ directories.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/sub-agents | 179, 183 | "Project subagents" / "Choose the subagent scope" — recursive-scan paragraph needs a closest-wins rule for cross-directory collisions |
| https://code.claude.com/docs/en/workflows | 178-179, 183 | "Save the workflow for reuse" — save-target and collision rules missing for nested .claude/workflows/ directories |
| https://code.claude.com/docs/en/output-styles | 51-53 | "Create a Markdown file" — three-bullet storage list missing the closest-wins rule for nested .claude/output-styles/ directories |

Total scope: 3 pages affected.

Cross-references:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/skills | Already documents the parallel "Automatic discovery from parent and nested directories" behavior and the <dir>:<name> clash convention from v2.1.178; use as a template for the agents / workflows / output-styles updates |
| https://code.claude.com/docs/en/changelog | v2.1.178 entry, line 16 — the new behavior was added there without a corresponding docs change on the three affected pages |
| https://code.claude.com/docs/en/permissions | Recursive scan of project subagents noted; should remain consistent with the new closest-wins rule |

Changelog version: v2.1.178