From 4642becb7a37df4429e3fbe1cbbad2b9b9f32018 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C2=ABSergei?= <enfros2000@gmail.com>
Date: Wed, 13 May 2026 13:13:34 +0300
Subject: [PATCH] docs: clarify plugin bin executables

---
 .../references/plugin-features-reference.md    | 18 ++++++++++++++++++
 .../skills/plugin-structure/SKILL.md           | 17 ++++++++++++++++-
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/plugins/plugin-dev/skills/command-development/references/plugin-features-reference.md b/plugins/plugin-dev/skills/command-development/references/plugin-features-reference.md
index c89e9060b4..526772c3c4 100644
--- a/plugins/plugin-dev/skills/command-development/references/plugin-features-reference.md
+++ b/plugins/plugin-dev/skills/command-development/references/plugin-features-reference.md
@@ -121,6 +121,24 @@ Lint results: !`node ${CLAUDE_PLUGIN_ROOT}/bin/lint.js $1`
 Review the linting output and suggest fixes.
 ```
 
+If the plugin ships an executable in `bin/`, the Bash tool can also invoke it
+as a bare command while the plugin is enabled:
+
+```markdown
+---
+description: Run bundled analyzer
+allowed-tools: Bash(analyze-project:*)
+---
+
+Analysis: !`analyze-project --format json $1`
+```
+
+Use `${CLAUDE_PLUGIN_ROOT}/scripts/...` for helper scripts that should only be
+called by your plugin internals. Use `bin/` for executable tools that should be
+discoverable as commands from Bash. Ensure files in `bin/` have executable
+permissions and that platform-specific binaries are packaged for the platforms
+you support.
+
 #### 2. Loading Configuration Files
 
 ```markdown
diff --git a/plugins/plugin-dev/skills/plugin-structure/SKILL.md b/plugins/plugin-dev/skills/plugin-structure/SKILL.md
index 6fb8a3baa1..d7c17430be 100644
--- a/plugins/plugin-dev/skills/plugin-structure/SKILL.md
+++ b/plugins/plugin-dev/skills/plugin-structure/SKILL.md
@@ -33,6 +33,7 @@ plugin-name/
 ├── hooks/
 │   └── hooks.json           # Event handler configuration
 ├── .mcp.json                # MCP server definitions
+├── bin/                     # Executables available as Bash bare commands
 └── scripts/                 # Helper scripts and utilities
 ```
 
@@ -41,7 +42,8 @@ plugin-name/
 1. **Manifest location**: The `plugin.json` manifest MUST be in `.claude-plugin/` directory
 2. **Component locations**: All component directories (commands, agents, skills, hooks) MUST be at plugin root level, NOT nested inside `.claude-plugin/`
 3. **Optional components**: Only create directories for components the plugin actually uses
-4. **Naming convention**: Use kebab-case for all directory and file names
+4. **Executable files**: Files in `bin/` must be executable on the target platform to run as bare Bash commands
+5. **Naming convention**: Use kebab-case for all directory and file names
 
 ## Plugin Manifest (plugin.json)
 
@@ -276,6 +278,19 @@ Use `${CLAUDE_PLUGIN_ROOT}` environment variable for all intra-plugin path refer
 - Script execution references
 - Resource file paths
 
+### Bundled Executables (`bin/`)
+
+Put command-line tools that users should invoke directly from the Bash tool in
+`bin/`. While the plugin is enabled, executable files in this directory are
+added to Bash command lookup, so a file such as `bin/my-tool` can be run as
+`my-tool --help` without spelling out `${CLAUDE_PLUGIN_ROOT}/bin/my-tool`.
+
+Use `scripts/` for helper scripts that are called by hooks, MCP servers, or
+commands through explicit `${CLAUDE_PLUGIN_ROOT}` paths. Use `bin/` for
+standalone tools intended to behave like commands. If you ship platform-specific
+binaries or scripts, include the right executable permissions and packaging for
+each supported platform.
+
 **Never use**:
 - Hardcoded absolute paths (`/Users/name/plugins/...`)
 - Relative paths from working directory (`./scripts/...` in commands)