Agent plugin authoring reference
AI agents: See llms.txt for documentation discovery and navigation. Documentation articles are also available as Markdown by appending .md to the article URL. Join VS Code at Microsoft Ignite or catch the sessions online. A year of VS Code, wrapped. Explore the highlights. Agent plugin authoring reference View as Markdown Ask in VS Code Ask in VS Code Insiders Package related customizations as a plugin that developers can install together.
This reference covers manifests, directory layouts, component and marketplace configuration, management commands, 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. Capability Description Client-specific Standard MCP servers External tool integrations ✓ Skills Instructions, scripts, and resources that load on-demand ✓ Agents Specialized personas and tool configurations ✓ Hooks Shell commands that run at specific points in the agent's workflow ✓ Automation templates Reusable prompts and schedules for agent tasks ✓ Slash commands Commands you can invoke with / in chat ✓ 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" } Field Type Required Description $schema string Yes Canonical Agent Plugins schema identifier. name string Yes Plugin name and package identifier. version string No Plugin version.
Semantic Versioning is recommended. description string No Brief description of the plugin. author object No Author information with optional name , email , and url fields. homepage string No Documentation or homepage. repository string No Source repository. license string No License identifier. An SPDX identifier is recommended. keywords string[] No Search and discovery terms. extensions object No Client-specific data keyed by reverse-domain namespace.
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 . Note Existing Copilot-format plugins that don't declare the Agent Plugins schema remain supported. For their manifest fields, see the GitHub Copilot CLI plugin reference . 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 format Plugin manifest Agent Plugins 1.0 plugin.json with $schema set to https://agent-plugins.org/schemas/1.0.0/plugin.schema.json Copilot plugin.json Claude .claude-plugin/plugin.json Legacy OpenPlugin .plugin/plugin.json 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. Plugin format Plugin root Agent Plugins 1.0 ${PLUGIN_ROOT} Claude ${CLAUDE_PLUGIN_ROOT} Copilot ${PLUGIN_ROOT} or ${CLAUDE_PLUGIN_ROOT} Legacy OpenPlugin ${PLUGIN_ROOT} 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. Note Automation templates are a VS Code-specific plugin capability, not a portable Agent Plugins 1.0 component type.
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: Field Required Description version Yes File format version.
Use 1 , or 2 when including disableConditions . id Yes Identifier that is unique within the plugin. Use lowercase letters, numbers, periods, or hyphens, with a maximum of 64 characters. name Yes Display name for the template. description No Short description of the automation's purpose. schedule Yes Manual, hourly, or five-field cron schedule. disableConditions No One afterDate condition with a date set to an ISO 8601 timestamp with a time zone.
Requires version 2 . To include an end date , use these fields alongside the other required frontmatter fields: version : 2 disableConditions : - kind : afterDate date : "2027-01-31T17:00:00Z" Replace the example timestamp with th
The rest of this page is on the live site.