[DOCS] Plugin docs missing `bin/` executables and Bash bare-command usage

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Environment variables, Plugin directory structure, and plugin/Bash runtime behavior for bundled executables

Current Documentation

The plugin reference currently says:

${CLAUDE_PLUGIN_ROOT}: the absolute path to your plugin's installation directory. Use this to reference scripts, binaries, and config files bundled with the plugin. This path changes when the plugin updates, so files you write here do not survive an update. A complete plugin follows this structure: ``text enterprise-plugin/ ├── .claude-plugin/ # Metadata directory (optional) │ └── plugin.json # plugin manifest ├── commands/ # Default command location ├── agents/ # Default agent location ├── skills/ # Agent Skills │ └── .../scripts/ ├── output-styles/ # Output style definitions ├── hooks/ # Hook configurations ├── settings.json # Default settings for the plugin ├── .mcp.json # MCP server definitions ├── .lsp.json # LSP server configurations ├── scripts/ # Hook and utility scripts │ ├── security-scan.sh │ ├── format-code.py │ └── deploy.js ``

The Bash tool docs currently say:

The Bash tool runs each command in a separate process with the following persistence behavior: Working directory persists across commands. Environment variables do not persist. An export in one command will not be available in the next.

There is no documentation describing a bin/ directory for plugins or that plugin-shipped executables can be invoked as bare commands from the Bash tool.

What's Wrong or Missing?

Changelog v2.1.91 added support for plugin-shipped executables under bin/ that can be invoked as bare commands from the Bash tool.

The current docs still describe bundled plugin binaries as files you reference via ${CLAUDE_PLUGIN_ROOT} and show scripts/ in the standard layout, but they do not explain this new behavior.

A. bin/ is not documented as part of plugin layout

The plugin structure docs do not show bin/ as a supported root-level directory for bundled executables.

B. Bare-command execution from Bash is not documented

The docs do not explain that these executables can be run from the Bash tool without writing the full ${CLAUDE_PLUGIN_ROOT}/... path.

C. Execution requirements and scope are unclear

There is no guidance on packaging requirements for these executables (for example executable permissions or platform-specific binaries), or on any caveats around this command-lookup behavior.

Suggested Improvement

Add a short Bundled executables (bin/) subsection to plugins-reference and a brief overview note to plugins.

Suggested content:

• Add bin/ to the standard plugin directory layout.
• State that executables shipped under bin/ can be run as bare commands from the Bash tool when the plugin is enabled.
• Clarify how this differs from existing ${CLAUDE_PLUGIN_ROOT}/scripts/... path-based examples used by hooks and MCP servers.
• Include one minimal example showing a plugin with bin/my-tool and a Bash invocation like my-tool --help.
• Document any requirements or caveats, such as executable permissions and platform-specific packaging where relevant.

A short cross-reference from tools-reference would also help, so the Bash tool docs mention that enabled plugins may contribute executable commands.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/plugins-reference | Primary technical reference for plugin layout, bundled files, ${CLAUDE_PLUGIN_ROOT}, and plugin cache behavior |
| https://code.claude.com/docs/en/plugins | Introductory plugin structure overview omits bin/ from the root-level directory table |
| https://code.claude.com/docs/en/tools-reference | Bash tool behavior page explains shell behavior but not plugin-provided bare commands |

Total scope: 3 pages affected

Source: Changelog v2.1.91

Exact changelog entry:

Plugins can now ship executables under bin/ and invoke them as bare commands from the Bash tool