Skip to content

Document plugin formats and environment variables#9634

Open
alexdioso wants to merge 1 commit intomicrosoft:mainfrom
alexdioso:clarify-plugin-formats
Open

Document plugin formats and environment variables#9634
alexdioso wants to merge 1 commit intomicrosoft:mainfrom
alexdioso:clarify-plugin-formats

Conversation

@alexdioso
Copy link
Copy Markdown
Contributor

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

Added sections on plugin formats and environment variables.
Copilot AI review requested due to automatic review settings April 8, 2026 18:37
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Suggested change
## Plugin Formats
## Plugin formats

Copilot uses AI. Check for mistakes.
| Copilot | `plugin.json`, `.github/plugin/plugin.json` |
| OpenPlugin | `.plugin/plugin.json` |

### Plugin Environment Variables
Copy link

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
### Plugin Environment Variables
### Plugin environment variables

Copilot uses AI. Check for mistakes.
Comment on lines +67 to +71
### Plugin Environment Variables
| Plugin format | Plugin root |
|---------------|------------------|
| Claude | `${CLAUDE_PLUGIN_ROOT}` |
| Copilot | (Not Defined) |
Copy link

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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) |

Copilot uses AI. Check for mistakes.
Comment on lines +61 to +72
| 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}` |
Copy link

Copilot AI Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants