# VS Code Agent Plugin

`forge plugin` packages forge's own skills, subagent templates, MCP server, and hooks into a portable **VS Code Agent Plugin** bundle — the `https://agent-plugins.org/schemas/1.0.0/plugin.schema.json` format that lets a third-party tool ship as one installable unit, instead of the several separate files every other adapter writes into VS Code's user config.

::: info Why VS Code gets its own bundle
Every other adapter in [Supported Agents](/guide/agents) writes forge's per-agent files (commands, subagents, MCP config) straight into that agent's native config directories via live injection. VS Code Copilot's subagent story works differently: `SupportsSubAgents()` on its adapter is deliberately `false` (see `internal/agents/vscode/adapter.go`), and subagent delivery instead goes through this plugin bundle, converting the same embedded templates into `com.github.copilot/agents/*.agent.md`. Turning the generic path on for VS Code too would write a second, conflicting copy outside the bundle.
:::

## `build` vs. `install`

```sh
forge plugin build [--out <dir>] [--cwd <dir>]
forge plugin install [--out <dir>]
```

| Subcommand | What it does |
| --- | --- |
| `build` | Writes the bundle to `<dir>` (default `.forge/vscode-plugin/`, relative to `--cwd`) for **manual** install via VS Code's *"Chat: Install Plugin From Source"* command |
| `install` | Writes the bundle straight to VS Code Copilot's auto-discovery location (default `~/.copilot/installed-plugins/forge/`) and registers it in VS Code's `settings.json` under `chat.pluginLocations` — no manual VS Code command needed |

Both are idempotent: files are only rewritten when their content actually changes, and `install`'s `settings.json` merge only appends the plugin location once — rerunning either command never duplicates content.

## What gets bundled

| File / directory | Content |
| --- | --- |
| `plugin.json` | The manifest — `$schema`, `name`, `version` (omitted for an unset/`dev` build), `description`, `author`, `homepage`, `repository`, `license`, `keywords` |
| `skills/` | Every embedded forge skill, copied verbatim (`SKILL.md` plus any `references/`/`scripts/` subfiles) — the same tree every other adapter's skills directory already uses |
| `com.github.copilot/agents/*.agent.md` | The 18 embedded Claude-format subagent templates (SDD phases plus the bounded-review lenses), converted through the same rendering path the live SDD injector uses for Claude Code, so review-lens agents carry their real resolved prompt body rather than an unresolved placeholder |
| `mcp.json` | Registers forge's own `forge mcp serve` stdio server under `mcpServers.forge` (the Agent Plugins 1.0 shape — not VS Code's own `servers`-keyed workspace/user format) |
| `com.github.copilot/hooks/hooks.json` | Wires `PostToolUse` to `forge hook post-tool-use` (feeds the [session timeline](/harness/timeline) and tool-call budget) and `SessionStart` to `forge hook session-start` (marks a session boundary on the timeline) — see [Connect a live agent](/harness/live-agent-hooks) |

The subagent templates' `{{CLAUDE_MODEL}}` placeholder resolves against forge's own shipped default preset (there is no live install session to source model assignments from when building a static bundle), and every entry in that preset uses the default effort, so the `{{CLAUDE_EFFORT_FRONTMATTER}}` placeholder is always stripped rather than resolved to a real `effort:` line.

## Verifying the install

After `forge plugin install`:

1. Confirm the bundle landed: `ls ~/.copilot/installed-plugins/forge/` should show `plugin.json`, `skills/`, `mcp.json`, and `com.github.copilot/`.
2. Confirm the registration: `chat.pluginLocations` in your VS Code `settings.json` should include that directory, alongside any settings already there — `install` merges rather than overwrites.
3. In VS Code, open Copilot Chat and check that the forge skills and agents are discoverable (skill/agent picker, or asking Copilot to list available agents).
4. If you built manually instead (`forge plugin build`), run VS Code's **"Chat: Install Plugin From Source"** command and point it at the output directory.

## Schema verification history

An earlier revision of this bundle shipped against a summarized (not primary-source) reading of the Agent Plugins format, and got three things wrong — caught by installing it into real VS Code and seeing what didn't show up. All three are fixed now, verified directly against `microsoft/vscode-docs`' `docs/agent-customization/agent-plugins.md` and the external [Agent Plugins 1.0 spec](https://agent-plugins.org/plugin-authors/mcp-servers):

| Component | Was | Now |
| --- | --- | --- |
| `mcp.json` | Top-level `servers` key, no transport `type` | Top-level `mcpServers` key (Agent Plugins 1.0's own `mcp.schema.json` shape, distinct from VS Code's workspace/user `servers`-keyed format), each entry carrying `"type": "stdio"` |
| `com.github.copilot/hooks/hooks.json` | Claude `settings.json`'s `{matcher, hooks: [...]}` nesting | VS Code's actual flat shape — each event maps directly to `[{type, command}]` |
| `forge plugin install`'s target | `~/.copilot/installed-plugins/forge/` (reserved for the Copilot CLI's own marketplace-bucketed installs, `<marketplace>/<plugin>/`) plus a `chat.pluginLocations` *array* | `~/.forge/vscode-plugin/`, registered via the documented **"Use local plugins"** mechanism — `chat.pluginLocations` as a path→bool *object* |

Folder placement itself (`skills/`, root `mcp.json`, `com.github.copilot/{agents,hooks/hooks.json}`) was correct from the start and is confirmed against the same primary doc.

::: warning One layout detail is still unconfirmed
The `com.github.copilot/agents/*.agent.md` file extension follows secondary-source research (VS Code's custom-agents doc) rather than a direct hit in the plugin-format doc itself, which shows the `agents/` directory without spelling out the filename convention inside it. Low risk, not yet independently re-verified.
:::

## Next steps

- [Supported Agents](/guide/agents) — how VS Code Copilot compares to every other adapter forge drives.
- [Connect a live agent](/harness/live-agent-hooks) — what the bundled `PostToolUse`/`SessionStart` hooks feed.
- [The forge CLI](/reference/cli#plugin) — the full `plugin` command synopsis and flags.
- [Skills: Registry & Discovery](/features/skills) — the skill files this bundle copies verbatim.