Copilot: Document Agent Plugins 1.0 support (#62640)

Co-authored-by: hkirschner_microsoft <hkirschner_microsoft@github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Sarita Iyer <66540150+saritai@users.noreply.github.com>
Copilot-Session: 7b920053-3358-460c-a9d2-824b058c7b55
Copilot-Session: bbcaf7d1-4485-4a30-809b-84d54cd03835

Author: 4 people

content/copilot/concepts/agents/about-plugins.md

@@ -25,19 +25,57 @@ Plugins provide a way to distribute custom {% data variables.product.prodname_co
 
 ## What plugins contain
 
-A plugin can contain some or all of the following components:
+A plugin can contain some or all of the following components. The locations of these components depend on the plugin format:
 
 * **Custom agents** — Specialized AI assistants (`*.agent.md` files in `agents/`)
 * **Skills** — Discrete callable capabilities (skills subdirectories in `skills/`, containing a `SKILL.md` file)
 * **Hooks** — Event handlers that intercept agent behavior (a `hooks.json` file in the plugin root, or in `hooks/`)
-* **MCP server configurations** — Model Context Protocol integrations (a `.mcp.json` file in the plugin root, or an `mcp.json` file in `.github/`)
+* **MCP server configurations** — Model Context Protocol integrations
 * **LSP server configurations** — Language Server Protocol integrations (an `lsp.json` file in the plugin root, or in `.github/`)
 
+## Plugin formats
+
+{% data variables.product.prodname_copilot_short %} supports two plugin formats:
+
+* **Agent Plugins 1.0** is a portable format for sharing skills and MCP server configurations across compatible clients. To use this format, set `$schema` in `plugin.json` to `https://agent-plugins.org/schemas/1.0.0/plugin.schema.json`. Skills are discovered from `skills/`, and MCP server configuration is discovered from `mcp.json` at the plugin root. These locations cannot be configured in the manifest. Choose Agent Plugins 1.0 when you want to make skills and MCP servers portable.
+* **Legacy {% data variables.product.prodname_copilot_short %} plugins** do not declare the Agent Plugins `$schema`. They use the existing manifest fields and component discovery behavior, including configurable component paths and MCP configuration in `.mcp.json`, `.github/mcp.json`, or the `mcpServers` manifest field. Choose the legacy format when you need configurable component paths or are maintaining an existing {% data variables.product.prodname_copilot_short %}-specific plugin.
+
+For a new plugin, use Agent Plugins 1.0 unless you require configurable component paths. Use the legacy format primarily for existing legacy plugins.
+
+Both formats are supported. Adding `$schema` changes how {% data variables.product.prodname_copilot_short %} interprets the manifest and discovers components. Plugins without `$schema` continue to load as legacy plugins.
+
 ## How plugins are structured
 
-A plugin is a directory with a specific structure. At minimum, it contains a `plugin.json` manifest file at the root of the directory. The manifest gives the plugin a name and points to the components the plugin provides. Alongside the manifest, the directory can contain any combination of agents, skills, hooks, MCP server configurations, and LSP server configurations.
+A plugin is a directory with a specific structure and a `plugin.json` manifest file. Agent Plugins 1.0 requires the manifest at the plugin root. Legacy plugins support additional manifest locations. The manifest gives the plugin a name and metadata. Depending on the format, it can also point to components. Alongside the manifest, the directory can contain agents, skills, hooks, MCP server configurations, and LSP server configurations.
+
+### Agent Plugins 1.0 structure
+
+Agent Plugins 1.0 stores skills and MCP servers in standard locations so compatible clients can discover them. Other components, including agents, hooks, commands, and LSP servers, are client-specific. {% data variables.product.prodname_copilot_short %} reads these components from the `com.github.copilot` directory. Other clients ignore this directory, so the same plugin can combine shared skills and MCP servers with {% data variables.product.prodname_copilot_short %}-specific components.
+
+An Agent Plugins 1.0 directory can look like this:
+
+```text
+my-plugin/
+├── plugin.json               # Required manifest
+├── skills/                   # Skills (optional)
+│   └── deploy/
+│       └── SKILL.md
+├── mcp.json                  # MCP server config (optional)
+└── com.github.copilot/       # Copilot components (optional)
+    ├── agents/
+    │   └── helper.agent.md
+    ├── commands/
+    ├── rules/
+    ├── hooks/
+    │   └── hooks.json
+    └── lsp.json
+```
+
+The manifest must include the Agent Plugins 1.0 `$schema`. For supported top-level manifest fields, name requirements, and component locations, see [Agent Plugins 1.0 manifest fields](/copilot/reference/copilot-cli-reference/cli-plugin-reference#agent-plugins-10-manifest-fields).
+
+### Legacy plugin structure
 
-A typical plugin directory looks like this:
+A legacy {% data variables.product.prodname_copilot_short %} plugin directory can look like this:
 
 ```text
 my-plugin/

content/copilot/how-tos/copilot-cli/customize-copilot/plugins-creating.md

@@ -22,38 +22,54 @@ Plugins are packages that extend the functionality of {% data variables.copilot.
 
 ## Plugin structure
 
-A plugin consists of a directory with a specific structure. At minimum, it must contain a `plugin.json` manifest file at the root of the directory. It can also contain any combination of agents, skills, hooks, and MCP server configurations.
-
-### Example plugin structure
-
-```text
-my-plugin/
-├── plugin.json           # Required manifest
-├── agents/               # Custom agents (optional)
-│   └── helper.agent.md
-├── skills/               # Skills (optional)
-│   └── deploy/
-│       └── SKILL.md
-├── hooks.json            # Hook configuration (optional)
-└── .mcp.json             # MCP server config (optional)
-```
+A plugin consists of a directory with a specific structure and a `plugin.json` manifest file. Agent Plugins 1.0 requires the manifest at the plugin root. Legacy plugins support additional manifest locations. A plugin can also contain any combination of agents, skills, hooks, and MCP server configurations.
+
+{% data variables.copilot.copilot_cli_short %} supports two plugin formats:
+
+* Agent Plugins 1.0, a portable format for skills and MCP servers. Declaring the canonical `$schema` in `plugin.json` opts the plugin into this format.
+* The legacy {% data variables.product.prodname_copilot_short %} format, which supports {% data variables.product.prodname_copilot_short %}-specific components and configurable component paths. A manifest without the Agent Plugins `$schema` continues to use this format.
+
+Both formats are supported. Choose Agent Plugins 1.0 when you want to make skills and MCP servers portable across compatible clients. Choose the legacy format when you need custom component paths or are maintaining an existing {% data variables.product.prodname_copilot_short %}-specific plugin. In Agent Plugins 1.0, skills and MCP servers are portable, and {% data variables.product.prodname_copilot_short %}-specific components such as agents, commands, rules, hooks, and LSP servers come from the `com.github.copilot` directory in the plugin.
 
 ## Creating a plugin
 
 1. Create a directory for your plugin.
-1. Add a `plugin.json` manifest file to the root of the directory.
+1. Choose a plugin format, then add a `plugin.json` manifest file to the root of the directory.
+
+   To create an Agent Plugins 1.0 plugin, include the canonical `$schema`:
 
-   **Example `plugin.json` file**
+   **Example Agent Plugins 1.0 `plugin.json` file**
 
    {% data reusables.copilot.copilot-cli.cli-example-plugin-file %}
 
+   The schema allows only `$schema`, `name`, `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords`, and `extensions` as top-level fields. Unknown top-level fields are reported and ignored. The `extensions` field is a map of client-specific data keyed by reverse-domain namespace.
+
+   To create a legacy plugin, omit the Agent Plugins `$schema`. You can use component path fields in the manifest:
+
+   **Example legacy `plugin.json` file**
+
+   ```json copy
+   {
+     "name": "my-dev-tools",
+     "description": "React development utilities",
+     "agents": "agents/",
+     "skills": ["skills/", "extra-skills/"],
+     "hooks": "hooks.json",
+     "mcpServers": ".mcp.json"
+   }
+   ```
+
    For details of the full set of fields you can include in this file, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-plugin-reference#pluginjson).
 
-1. Add some components to your plugin by creating the appropriate files and directories for agents, skills, hooks, and MCP server configurations.
+1. Add components to your plugin.
+
+   In an Agent Plugins 1.0 plugin, skills must be immediate subdirectories of `skills/`, and each skill must contain a `SKILL.md` file. MCP configuration must be in `mcp.json` at the plugin root. You cannot override these locations in `plugin.json`. {% data variables.product.prodname_copilot_short %}-specific components go in the `com.github.copilot` directory, such as `com.github.copilot/agents/` for custom agents and `com.github.copilot/hooks/hooks.json` for hooks.
+
+   In a legacy plugin, use the default component locations or the component paths configured in `plugin.json`.
 
    For example:
 
-   1. Add an agent by creating a `NAME.agent.md` file in an `agents` subdirectory.
+   1. Add an agent by creating a `NAME.agent.md` file in an `agents` subdirectory. In an Agent Plugins 1.0 plugin, create the file in `com.github.copilot/agents/`. In a legacy plugin, create it in `agents/`.
 
       ```markdown copy
       ---
@@ -78,6 +94,31 @@ my-plugin/
       Instructions for the skill...
       ```
 
+   1. For an Agent Plugins 1.0 plugin, add MCP servers in a root `mcp.json` file. The MCP configuration uses its own Agent Plugins schema:
+
+      ```json copy
+      {
+       "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+       "mcpServers": {
+         "deployment-api": {
+           "type": "streamable-http",
+           "url": "https://deploy.example.com/mcp"
+         },
+         "local-validator": {
+           "type": "stdio",
+           "command": "node",
+           "args": ["${PLUGIN_ROOT}/server/index.js"],
+           "cwd": "${PLUGIN_ROOT}",
+           "env": {
+             "DATA_DIR": "${PLUGIN_DATA}/validator"
+           }
+         }
+       }
+      }
+      ```
+
+      The `streamable-http` transport name is accepted for Streamable HTTP servers. For `stdio` servers, {% data variables.copilot.copilot_cli_short %} provides `PLUGIN_ROOT` and `PLUGIN_DATA` environment variables and expands `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` in `args`, `env` values, and `cwd`.
+
 1. Install your plugin locally, so that you can test it as you develop it.
 
    For example, where `./my-plugin` is the path to your plugin directory, enter:
@@ -137,5 +178,6 @@ To distribute your plugin, you can add it to a marketplace. See [AUTOTITLE](/cop
 
 ## Further reading
 
+* [Agent Plugins author documentation](https://agent-plugins.org/plugin-authors)
 * [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing)
 * [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-plugin-reference)