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.

Why VS Code gets its own bundle

Every other adapter in Supported 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

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 and tool-call budget) and SessionStart to forge hook session-start (marks a session boundary on the timeline) — see Connect a live agent

The subagent templates' 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 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:

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.

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 — how VS Code Copilot compares to every other adapter forge drives.
• Connect a live agent — what the bundled PostToolUse/SessionStart hooks feed.
• The forge CLI — the full plugin command synopsis and flags.
• Skills: Registry & Discovery — the skill files this bundle copies verbatim.