Document plugin formats and environment variables#9634
Document plugin formats and environment variables#9634alexdioso wants to merge 1 commit intomicrosoft:mainfrom
Conversation
Added sections on plugin formats and environment variables.
There was a problem hiding this comment.
Pull request overview
This PR updates the agent plugins documentation to clarify how VS Code detects different plugin formats based on plugin.json location, and which plugin-root environment variable (if any) is available for hooks.
Changes:
- Documented how VS Code auto-selects the plugin format based on the plugin file path.
- Added a table describing which plugin-root variable is available per plugin format.
| > [!CAUTION] | ||
| > Plugins can include hooks and MCP servers that run code on your machine. Review the plugin contents and publisher before installing, especially for plugins from community marketplaces. | ||
|
|
||
| ## Plugin Formats |
There was a problem hiding this comment.
Use sentence-style capitalization for headings to match the rest of this doc. For example, change ## Plugin Formats to ## Plugin formats (and keep a blank line after the heading for consistency with other sections).
| ## Plugin Formats | |
| ## Plugin formats |
| | Copilot | `plugin.json`, `.github/plugin/plugin.json` | | ||
| | OpenPlugin | `.plugin/plugin.json` | | ||
|
|
||
| ### Plugin Environment Variables |
There was a problem hiding this comment.
This heading should also use sentence-style capitalization (for example, ### Plugin environment variables) and include a blank line after the heading, consistent with other sections in this file.
| ### Plugin Environment Variables | |
| ### Plugin environment variables |
| ### Plugin Environment Variables | ||
| | Plugin format | Plugin root | | ||
| |---------------|------------------| | ||
| | Claude | `${CLAUDE_PLUGIN_ROOT}` | | ||
| | Copilot | (Not Defined) | |
There was a problem hiding this comment.
The table under "Plugin environment variables" lists values like ${CLAUDE_PLUGIN_ROOT} / ${PLUGIN_ROOT}, which reads like a configuration token, not an environment variable name. Consider either (1) listing the actual env var names (CLAUDE_PLUGIN_ROOT, PLUGIN_ROOT) or (2) renaming the column/section to explicitly describe tokens vs injected environment variables, so readers know what to use in JSON vs in a shell script.
| ### Plugin Environment Variables | |
| | Plugin format | Plugin root | | |
| |---------------|------------------| | |
| | Claude | `${CLAUDE_PLUGIN_ROOT}` | | |
| | Copilot | (Not Defined) | | |
| ### Plugin root tokens | |
| | Plugin format | Plugin root token | | |
| |---------------|-------------------| | |
| | Claude | `${CLAUDE_PLUGIN_ROOT}` | | |
| | Copilot | (Not defined) | |
| | Plugin format | Plugin file path(s) | | ||
| |---------------|------------------| | ||
| | Claude | `.claude-plugin/plugin.json` | | ||
| | Copilot | `plugin.json`, `.github/plugin/plugin.json` | | ||
| | OpenPlugin | `.plugin/plugin.json` | | ||
|
|
||
| ### Plugin Environment Variables | ||
| | Plugin format | Plugin root | | ||
| |---------------|------------------| | ||
| | Claude | `${CLAUDE_PLUGIN_ROOT}` | | ||
| | Copilot | (Not Defined) | | ||
| | OpenPlugin | `${PLUGIN_ROOT}` | |
There was a problem hiding this comment.
This section introduces an OpenPlugin format and a ${PLUGIN_ROOT} root token, but later sections in this article only document Claude/Copilot paths and only describe ${CLAUDE_PLUGIN_ROOT} for hooks and MCP servers. Either add OpenPlugin-specific details in those later sections (hook file location, path tokens for hooks/MCP), or explicitly state here that OpenPlugin-format plugins are not supported for hooks/MCP in VS Code (if that's the case).
Added sections on plugin formats and environment variables. I had to dig through the vscode source to figure out why plugin hooks weren't working properly. Turns out that the plugin root is not provided to hooks when using Copilot format plugins. OpenPlugin and Claude format plugins get different plugin root environment variables. These changes should help clear up when each plugin format type is used and what root environment variable is provided (if any).
Plugin file path selection
Environment variables for plugin type