[DOCS] `claude agents --plugin-dir <dir>` is documented but never warns about flag placement after `agents`

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The claude agents row in cli-reference.md and the matching command table in agent-view.md.

Current Documentation

cli-reference.md:28 documents claude agents as accepting --plugin-dir:

| claude agents | Open agent view to monitor and dispatch parallel background sessions. Use --cwd <path> to show only sessions started under that directory, or --json to print active sessions as a JSON array for scripting (--json --all also includes completed background sessions). Pass --permission-mode, --model, --effort, or --agent to set defaults for dispatched sessions. Accepts --settings, --add-dir, --plugin-dir, and --mcp-config like the top-level claude command. Opening agent view requires an interactive terminal | claude agents --json |

agent-view.md:459-463 documents the same flags for dispatched sessions:

| --plugin-dir <path> | Load a plugin from a local directory | Repeat --add-dir, --plugin-dir, or --mcp-config once per value. The space-separated form, such as --add-dir a b, isn't supported with claude agents.

The example column for claude agents in cli-reference.md reads claude agents --json.

What's Wrong or Missing?

A. v2.1.200 fixed a flag-after-subcommand bug

The v2.1.200 changelog says:

Fixed claude agents --plugin-dir <dir> not showing the plugin's agents and skills in the agent view when the flag is placed after agents

Before v2.1.200, claude agents --plugin-dir ./my-plugin silently dropped the plugin's agents and skills in the agent view, even though the same flag placed before agents (or after the top-level claude command) worked correctly. The current docs do not warn about flag placement and do not say that the bug only manifested after agents.

B. The "Repeat --add-dir, --plugin-dir, or --mcp-config" note implies any position

agent-view.md:463 says to repeat the flag once per value, with no guidance on whether the flag has to come before or after the agents subcommand. A reader of the v2.1.199 docs could place --plugin-dir after agents and not realize the agent view would silently show fewer plugins than expected.

C. No working example of claude agents --plugin-dir

cli-reference.md's example column for claude agents shows claude agents --json rather than claude agents --plugin-dir ./my-plugin. The page never shows the flag in a working invocation, so users discovering the option have no anchor.

Suggested Improvement

Add a sentence to the claude agents row in cli-reference.md, for example:

claude agents … Accepts --settings, --add-dir, --plugin-dir, and --mcp-config like the top-level claude command. As of v2.1.200, --plugin-dir is honored regardless of whether it appears before or after the agents subcommand; earlier versions silently dropped the plugin's agents and skills in the agent view when the flag was placed after agents.

Update the example column to include claude agents --plugin-dir ./my-plugin alongside claude agents --json, and add a corresponding note in agent-view.md under the flag list.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/cli-reference | 28 | claude agents row |
| https://code.claude.com/docs/en/agent-view | 459-463 | "Flags for dispatched sessions" table |

Total scope: 2 pages, both listing the same flags.

The release note for this fix appears in v2.1.200 (July 3, 2026).