Host support: Copilot editor/VS Code — Agent Plugins namespace, hooks, skills, instructions, and MCP

[ScriptedAlchemy]

Scope / evidence

P2 feature expansion. Research date 2026-09-06; baseline 5fc8de37c9695b816d55bdcf18a6bcb1dfee69f5. Read Microsoft/GitHub primary documentation; no editor installation or native test performed.

Correction to Ponytail-only research: current VS Code Copilot supports installable agent plugins, not merely .github/copilot-instructions.md. This issue targets the VS Code agent harness first. Other Copilot editor integrations require their own verified capability profiles; do not claim JetBrains/Visual Studio parity from VS Code documentation. Standalone Copilot CLI is #698.

Primary specifications and setup guides

• Agent plugins: formats, schema, namespaces, install and local paths
• Agent Plugins manifest schema
• Agent Plugins standard
• VS Code hooks guide and compatibility differences
• Exact hook input/output reference
• Agent Skills
• MCP setup, scopes, remote hosts and trust
• Agent customization concepts
• Copilot CLI native format reference, for comparison only

Pin the tested VS Code and Copilot/agent-harness versions. Hook functionality is currently labelled Preview; enterprise policy can disable it.

Native package contract

Agent Plugins mode uses root plugin.json with the canonical $schema, standard skills/ and mcp.json, and a client-owned com.github.copilot/ namespace for agents, commands, rules and hooks. Existing native Copilot, Claude and legacy OpenPlugin formats have different discovery rules. Avoid adding unsupported top-level fields to the portable manifest.

Proposed output:

composite-root/
  plugin.json
  skills/review/SKILL.md
  mcp.json
  com.github.copilot/
    agents/reviewer.agent.md
    commands/review.md
    hooks/hooks.json
  hooks/vscode-before.mjs
  mcp/example.mjs

{
  "$schema":"https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name":"example-plugin",
  "version":"1.0.0",
  "description":"Project review capabilities"
}

Use existing portable output when it already satisfies the native contract. Shared namespace contents can benefit #698, but callback behavior still needs host-specific tests. An agent plugin is not a VSIX extension; do not create an editor extension just to distribute skills/MCP/hooks.

Installation, development and scope

Run Chat: Install Plugin From Source, or browse @agentPlugins in Extensions and review marketplace trust. Local development uses the documented setting:

{
  "chat.plugins.enabled": true,
  "chat.pluginLocations": {
    "/absolute/composite-root": true
  }
}

Marketplaces use chat.plugins.marketplaces; enabled/disabled state can differ by workspace. VS Code can discover plugins already installed by Copilot CLI, so installing a second copy may duplicate behavior. Implement receipt-owned registration and native inventory checks rather than rewriting the entire settings file. Preserve disabled state and operator consent; package updates from external sources have explicit native approval behavior.

MCP is a separate configuration layer

A plugin's portable mcp.json is not the same schema/location as workspace .vscode/mcp.json. The latter uses servers, for example:

{"servers":{"example":{"type":"stdio","command":"node","args":["/absolute/plugin/mcp/example.mjs"]}}}

Prefer plugin-bundled registration to duplicate standalone entries. Native user-profile, workspace, remote and Agent Host sessions resolve execution locations differently. Some interactive input-variable configurations cannot be forwarded to Agent Host. Select native root/data anchors and secret input mechanisms deliberately, preserve remote OS paths, and never infer that a local host process runs beside a remote workspace.

Hook codec differences that must not be hidden

VS Code reads several compatible hook formats, but its current guide states that Claude matcher expressions are parsed and ignored. Tool names and tool-input property naming also differ. Preserve a canonical filter inside the generated wrapper when the native matcher cannot enforce it, or reject the requested mapping; never accidentally broaden an action-sensitive hook to every tool.

Use the exact per-event output reference: stopping the session is different from denying one tool; systemMessage is user-facing and is not arbitrary context injection. OS overrides follow the extension host platform. Native plugin hooks combine with other registered hooks, so returning allow must not erase an unrelated deny.

Illustrative namespaced hook config:

{"hooks":{"PreToolUse":[{"type":"command","command":"node ${PLUGIN_ROOT}/hooks/vscode-before.mjs","timeout":15}]}}

The supported placeholder/quoting form must be validated for each OS and runtime profile. Do not copy a hook command that embeds the build checkout or defaults to approval bypass.

Acceptance

• Pin schema and VS Code/harness versions; identify unsupported editor profiles and preview gates.
• Portable content-only package loads without MCP/Flight/state processes.
• Namespaced components are discovered once; foreign client namespaces are ignored; root/Claude/legacy manifest combinations have tested precedence.
• Local and CLI-installed plugin discovery does not duplicate registration.
• Generated tool succeeds after actual install/relocation with correct schema, result, cancellation, environment and writable-data scope.
• Test native matcher incompatibility, tool-name/property mapping, per-tool deny versus session stop and combined-hook behavior.
• Remote extension host paths and OS overrides work or yield explicit unsupported diagnostics.
• Native trust/enterprise policy/disabled state remain unchanged; update/remove preserves unrelated settings and data.
• Optional MCP App output is verified separately from plain tools; no blanket claim from server startup.
• Extend Composite conformance: test cross-host auto-discovery and precedence, not only file collisions #651/Small-plugin acceptance: skills and plain hooks without an unnecessary MCP/RSC runtime or empty Workbench #652 composite and small-plugin acceptance; record successful real editor invocation separately from parser tests.

Reuse canonical manifests, operation graphs, launch records, codecs and receipts. No custom VSIX, new agent orchestration, provider/account management, universal permission grant, or global removal of AB4106.

[ScriptedAlchemy]

Resolved by #723 (4dc11a4a06).

VS Code (Copilot agent plugins) — observed code.visualstudio.com/docs/agent-customization/agent-plugins, page footer 9/2/2026, retrieved 2026-09-06. Supported: the emitted package installs as one plugin.

Surface	State	Evidence
manifest	supported	2026-09-06: the page discriminates formats by the root manifest's $schema and links the canonical manifest, MCP, and client-extension documents at agent-plugins.org, plus the 1.0.0 specification text — the identifiers this projection emits.
skills	supported	2026-09-06: the page states "Skills are discovered from the skills/ folder, and MCP server configuration is discovered from the mcp.json file. You don't list these component paths in the manifest" — the fixed locations this projection emits.
mcp	supported	2026-09-06: the page states "Place MCP server definitions in the mcp.json file at the plugin root and follow the portable MCP configuration format", linking the canonical portable MCP document.
placeholders	unavailable	2026-09-06: the page contradicts itself on the reserved placeholders — it names ${PLUGIN_ROOT} and ${PLUGIN_DATA} and in one place says they are expanded and in another that they are preserved — so §9.1 expansion in args, env values, and cwd is not established for the emitted mcp.json.
hooks	unavailable	2026-09-06: VS Code reads plugin hooks from com.github.copilot/hooks/hooks.json, a client-specific namespace directory this projection does not write, and Agent Plugins 1.0.0 defines no hooks; the surface is also documented as Preview.

Paths it reads: mcp.json, plugin.json, skills.
Install: "chat.pluginLocations": { "<plugin directory>": true }.

Every row above is pinned to that client's own documentation on the date shown, is validated on every build, and renders in INSTALL.md and the generated hosts reference. A surface recorded unavailable or degraded names exactly what the client would need; no unsupported feature is projected silently.

[ScriptedAlchemy]

Current-main reconciliation

The vs-code portable-client record landed in #723. Its remaining action-label correction is now #728, not a new native-adapter requirement: at b5cf7575e0bcfa6da23e12d2c5628146bdbe5cb1, chat.pluginLocations is still tagged install even though it registers the existing directory in place. The shared register action role already landed and is used for Pi, Swival and Junie.

Use that existing role and test rendered INSTALL.md/reference text against VS Code's documented local-registration behavior. Keep the documented enabled/disabled state and unverified placeholder/manifest-precedence limits intact. Do not change copied-skill actions such as Cline's cp -R to registration merely to make labels uniform.

The completed compatibility record should not be described as generated com.github.copilot hook/agent extensions or as a successful native execution test. No broad reopening or second catalog is needed.