Document plugin formats and environment variables#9634
Open
alexdioso wants to merge 3 commits intomicrosoft:mainfrom
Open
Document plugin formats and environment variables#9634alexdioso wants to merge 3 commits intomicrosoft:mainfrom
alexdioso wants to merge 3 commits intomicrosoft:mainfrom
Conversation
Added sections on plugin formats and environment variables.
Contributor
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.
Comment on lines
+67
to
+71
| ### 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.
Suggested change
| ### 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) | |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
ntrogh
requested changes
Apr 13, 2026
Contributor
ntrogh
left a comment
ntrogh
left a comment
There was a problem hiding this comment.
@alexdioso Thanks for contributing. I added some corrections for style and technical accuracy.
| > 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 | ||
| The plugin format is auto-selected based on the plugin file path (relative to the plugin root). |
Contributor
There was a problem hiding this comment.
Suggested change
| The plugin format is auto-selected based on the plugin file path (relative to the plugin root). | |
| VS Code auto-detects the plugin format by checking for format-specific manifest paths. Copilot format is used as the default when no other format markers are found. |
| | Plugin format | Plugin file path(s) | | ||
| |---------------|------------------| | ||
| | Claude | `.claude-plugin/plugin.json` | | ||
| | Copilot | `plugin.json`, `.github/plugin/plugin.json` | |
Contributor
There was a problem hiding this comment.
Suggested change
| | Copilot | `plugin.json`, `.github/plugin/plugin.json` | |
| | Plugin format | Plugin root | | ||
| |---------------|------------------| | ||
| | Claude | `${CLAUDE_PLUGIN_ROOT}` | | ||
| | Copilot | (Not Defined) | |
Contributor
There was a problem hiding this comment.
Suggested change
| | Copilot | (Not Defined) | | |
| | Copilot | (Not defined) | |
| | Copilot | `plugin.json`, `.github/plugin/plugin.json` | | ||
| | OpenPlugin | `.plugin/plugin.json` | | ||
|
|
||
| ### Plugin environment variables |
Contributor
There was a problem hiding this comment.
Suggested change
| ### Plugin environment variables | |
| ### Plugin environment variables | |
| Some plugin formats provide a root token that you can use in hook commands and MCP server configurations to reference files within the plugin directory. VS Code expands the token at runtime and also sets it as an environment variable in the hook or server process. | |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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