Agent plugin authoring reference

Package related customizations as a plugin that developers can install together. This reference covers manifests, directory layouts, component configuration, and compatibility across plugin formats and agent harnesses.

Use it when creating a plugin or inspecting how its components are configured. To find, install, update, or remove an existing plugin, see Use agent plugins.

Package structure

Agent Plugins 1.0 defines skills and MCP servers as portable component types. Other capabilities are client-specific and use the standard's reverse-domain client extension namespaces. VS Code reads Copilot-specific components from the com.github.copilot namespace and ignores namespaces owned by other clients.

For example, a testing plugin might include a test-runner skill with scripts, a test-reviewer agent with read-only tools, and an MCP server for a test reporting dashboard. In the Agent Plugins format, the directory structure looks like this:

my-testing-plugin/
  plugin.json              # Plugin metadata and configuration
  skills/
    test-runner/
      SKILL.md             # Testing skill instructions
      run-tests.sh         # Supporting script
  mcp.json                 # MCP server definitions
  automations/
    review.automation.md   # Automation template
  scripts/
    validate-tests.sh      # Hook script
  com.github.copilot/
    agents/
      test-reviewer.agent.md  # Code review agent
    hooks/
      hooks.json           # Hook configuration

Plugins in the Copilot and Claude formats provide the same capabilities from different locations. See Plugin formats.

Plugin manifest (plugin.json)

An Agent Plugins 1.0 package has a plugin.json file at its root that declares the standard's schema:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-dev-tools",
  "description": "React development utilities",
  "version": "1.2.0"
}

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. Custom agents, hooks, commands, and MCP server definitions are not portable top-level manifest fields.

Copilot-specific components live in the com.github.copilot directory at the plugin root, and Copilot-specific manifest data goes under the matching key in extensions:

my-plugin/
  plugin.json              # $schema declares Agent Plugins 1.0
  skills/                  # Portable: agent skills
  mcp.json                 # Portable: MCP server configuration
  com.github.copilot/      # Copilot-specific components
    agents/
    commands/
    rules/
    hooks/
      hooks.json

Other clients ignore the com.github.copilot namespace, so a package stays portable while keeping its Copilot capabilities.

For the full field constraints and validation rules, see the Agent Plugins manifest documentation.

Plugin formats

VS Code auto-detects the plugin format by checking the root manifest and format-specific manifest paths. A root plugin.json that declares the canonical Agent Plugins $schema uses Agent Plugins semantics. The Copilot format is used as the default when no other format marker is found.

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.

Agent Plugins 1.0 also defines ${PLUGIN_ROOT} for packaged files and ${PLUGIN_DATA} for writable state that persists across plugin updates. VS Code preserves these placeholders for the plugin runtime to expand. For details about where placeholders are supported, see the Agent Plugins specification.

Automations in plugins

Agent Plugins can contribute automation templates that appear under Templates from Plugins in the Agents window. A template provides a reusable name, prompt, and schedule. It doesn't create or enable an automation when the plugin is installed.

Automation template location

Store automation templates in an automations/ folder at the root of an Agent Plugins package. Each file must use the .automation.md suffix:

my-plugin/
  plugin.json
  automations/
    daily-review.automation.md
    weekly-review.automation.md

To add templates from other folders, configure extensions.com.github.copilot.automations.paths in plugin.json. These paths are relative to the com.github.copilot/ folder and supplement the default automations/ folder:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-dev-tools",
  "version": "1.2.0",
  "extensions": {
    "com.github.copilot": {
      "automations": {
        "paths": ["./team-automations/"]
      }
    }
  }
}

Set exclusive to true alongside paths to load templates only from the configured folders and skip the default automations/ folder.

Automation template format

An automation template is a Markdown file with YAML frontmatter. The Markdown body is the prompt:

---
version: 1
id: weekly-review
name: Weekly review
description: Review the workspace for regressions.
schedule:
  kind: cron
  expression: "30 10 * * 5"
  timeZone: local
---
Review the workspace changes from the past week.
Identify regressions and suggest follow-up actions.

The frontmatter supports these fields:

Use one of these schedule formats:

The five cron fields represent minute, hour, day of month, month, and day of week. Only local-time cron expressions that represent a daily or weekly schedule are supported. VS Code ignores invalid templates rather than changing their schedule.

Plugin templates can't specify a workspace, provider, model, permissions, enabled state, or run history. When someone selects a template, the New Automation dialog opens so they can review the prompt and choose the execution configuration. The Enabled checkbox is cleared by default.

Disabling a plugin removes its templates from the Automations view. Automations that were previously created from those templates and their run history remain available.

MCP servers in plugins

Plugins can bundle MCP servers to provide agents with additional tools and data sources. Plugin MCP servers start automatically when the plugin is enabled and stop when the plugin is disabled.

MCP configuration file

my-plugin/
  plugin.json             # Plugin metadata and configuration
  skills/
  mcp.json              # MCP server definitions
  servers/
    db-server             # Server executable
  config.json             # Server configuration

my-plugin/
  plugin.json             # Plugin metadata and configuration
  skills/
  .mcp.json              # MCP server definitions
  servers/
    db-server             # Server executable
  config.json             # Server configuration

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

How plugin MCP servers interact with other servers

Plugin MCP servers appear alongside workspace and user-level MCP servers. You can manage them through the same tools:

• Select Configure Tools in the Chat view to see tools from all MCP servers, including plugin servers.

• Run MCP: List Servers from the Command Palette to view plugin servers alongside other servers.

Plugin MCP servers are implicitly trusted when you install the plugin. Unlike workspace MCP servers, they do not show a separate trust prompt at startup.

Disabling a plugin stops its MCP servers. Tools provided by the stopped servers are no longer available in chat.

Hooks in plugins

Plugins can include hooks that run shell commands at agent lifecycle points. Plugin-wide hooks work alongside your workspace and user-level hooks. When a plugin is enabled, these hooks fire in addition to any other hooks configured for the same event.

Organizations can distribute approved hooks through plugins. When managed settings specify allowManagedHooksOnly: true, plugin hooks run only when the plugin is force-enabled by a managed enabledPlugins["plugin@marketplace"]: true entry. User enablement alone is not sufficient, and allowManagedHooksOnly does not itself enable the plugin. See Deploy hooks through managed plugins.

For Copilot sessions, use the Copilot hooks reference for configuration, event payloads, and output decisions. A plugin packages hooks; it does not translate Local scripts into the shared harness's contract.

When adopting or updating a plugin, follow Migrate hooks. Update the source package, not its installation cache. Check bundled scripts, path references, agent-scoped hooks, and any duplicate commands in user settings or repository hook files.

Hook file location

The hook file location depends on the plugin format:

VS Code auto-detects the plugin format and discovers the hook file automatically.

my-plugin/
  plugin.json
  com.github.copilot/
    hooks/
      hooks.json         # Hook configuration (Agent Plugins format)
  scripts/
    review-tool-copilot.cjs

Hook configuration format

Use the hook schema supported by the plugin's target runtime. For Copilot, review the command-hook format and matcher semantics. Event aliases can affect payload and tool names, so test scripts and matchers together.

Reference plugin paths in hook commands

Use a plugin-root reference rather than hardcoding its installation directory. These references identify the package root, not the current repository or the folder containing the hook configuration:

For example, include the converted review script as scripts/review-tool-copilot.cjs in the package structure above. In an Agent Plugins 1.0 package, put this configuration in com.github.copilot/hooks/hooks.json:

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "command": "node \"${PLUGIN_ROOT}/scripts/review-tool-copilot.cjs\"",
        "env": { "REVIEW_TOOL_NAME": "<copilot-tool-name>" },
        "timeoutSec": 10
      }
    ]
  }
}

Replace <copilot-tool-name> with the tool to review. The quoted script path keeps installations containing spaces as one command argument. This example requires Node.js on the execution host and does not write into the installed package.

The plugin parser defines the format-specific hook-root references and their command-path expansion. Use the token and hook-file location for your package format; do not copy an installed cache path. Before testing the package in a disposable Copilot session, deactivate any standalone copy of the same hook.

Supported hook events

Use the shared harness's event reference for plugin-wide hooks.

Hooks in a plugin-provided custom agent's frontmatter have a separate conversion limitation: VS Code currently omits the agent's hooks field when passing that agent to the Copilot harness. The agent appearing in the picker does not prove its hooks run. Retain the scoped definition and leave its migration incomplete until this conversion is supported and verified. A plugin-wide hook is not an equivalent workaround.

How plugin hooks interact with other hooks

Plugin-wide hooks run alongside other applicable hook sources. For Copilot preToolUse, a denial blocks the tool call. Return no decision when the hook should leave the normal permission flow unchanged. Review the runtime's timeout and failure rules before relying on a hook for validation.

Disabling a plugin also disables its hooks. Unless enterprise policy controls the plugin's enablement, you can enable or disable plugins globally or for a specific workspace from the Extensions view.

Cross-tool compatibility

Agent Plugins 1.0 is an open standard designed for cross-tool compatibility. A conformant plugin uses a root plugin.json, puts skills in skills/, and puts MCP server configuration in mcp.json. Compatible clients can discover the portable component types they support from the same package.

Agent Plugins can also include client-specific manifest data and files under a stable reverse-domain namespace. Clients ignore namespaces they don't implement, so client-specific capabilities don't prevent other clients from loading the portable components. VS Code reads custom agents, slash commands, rules, hooks, and automation path configuration from the com.github.copilot namespace. Other clients only use the capabilities in that namespace that they support.

For example:

my-plugin/
  plugin.json
  skills/
  mcp.json
  com.github.copilot/      # Read by VS Code and other Copilot clients
  com.example.client/      # Ignored by VS Code

VS Code continues to support existing Copilot, Claude, and legacy OpenPlugin formats. Plugins that don't declare the Agent Plugins schema continue to use their existing format-specific discovery rules.

For details about the portable format, see the Agent Plugins specification. For other formats, see the GitHub Copilot CLI plugin reference and the Claude Code plugin marketplace documentation.

Test and distribute a plugin

Before distributing a plugin, verify its behavior with each harness and client you intend to support:

1. Register your development copy as a local plugin. This configuration is Experimental.
2. Check that its supported components appear, then run a representative task to verify the skills, agents, hooks, and tools that the plugin provides. Review any code that a hook or MCP server runs before testing.
3. If the plugin includes automation templates, confirm that they appear in Templates from Plugins and review their configuration before creating an automation.
4. Before publishing an update, bump the version field in plugin.json and in the marketplace.json plugin entry, if applicable. Follow the marketplace schema for your plugin format.
5. Test the installation and update paths that developers will use.

For marketplace schemas and distribution details, see the Agent Plugins specification, the GitHub Copilot CLI plugin reference, and the Claude Code marketplace documentation.

Related resources

• Create agent skills
• Create custom agents
• Configure agent hooks