If you read my earlier post on creating agent plugins for VS Code and Copilot CLI, it offered a new way to distribute your agentic resources: put your agents, skills, and tool integrations in a package that a team can install. As features and clients evolved, though, the format started to become a bit messy – it was slightly different between clients. To make matters more challenging, there was no well-defined way to separate vendor-specific agentic content from vendor-neutral features, like skills. Thankfully, OpenAI, AWS, Microsoft, Cursor, and Vercel agreed to adopt a single open specification. Sadly, Anthropic has not announced support yet.
The Agent Plugins 1.0 specification was finally released on August 6, and it is now the recommended go-forward format. It defines a vendor-neutral way to package Agent Skills and Model Context Protocol (MCP) server configurations. Better still, it now cleanly separates content that is vendor-specific from “common core” content.
If you haven’t built much agentic content, some features – like agent profiles – tend to have client-specific metadata. Often, that metadata is not actually portable across vendors. For example, take the model field, which specifies the AI model you want your profile to use. VS Code Copilot allows an array of models, and it uses the first recognized one. For other tools, this is a string – you can specify only one model. Rather than trying to make one format fit all clients, the specification allows vendors to define their own features in a separate extension directory, isolating them from shared, portable content.
In short, this is more than a rename. It gives you a clean answer to a difficult question: which parts of a custom agent experience should be consistently defined across harnesses, and which parts deliberately belong to a specific client?
Start with a portable core
An Agent Plugin is simply a directory with organized files, typically stored in Git. A compact release-helper plugin could look like this:
The portable components are always at the root. Today, that means the manifest file (plugin.json), the skills folder, and the mcp.json file that defines the MCP server configuration.
A plugin does not need every component, but it does require a manifest that provides some basic metadata about the plugin and its version:
It is important to know that this is the minimum set of required elements. That includes the $schema element. Without it, clients will often interpret the plugin using their earlier, proprietary plugin format.
Copilot features … without losing portability
Skills and MCP configurations are portable, but some Copilot features, such as agents, hooks, and Language Server Protocol (LSP) servers, are not part of the Agent Plugins 1.0 core. That is where the vendor extensions come in. Each vendor can define a reverse-domain directory for its client-specific extensions and features. Instead of all vendors sharing a single incompatible agents folder, each vendor gets a unique namespace for any feature that may not have a “core” definition. GitHub Copilot uses com.github.copilot. Clients that do not understand this namespace can ignore it while continuing to load the portable root.
First, the plugin manifest must declare content in that namespace in the root manifest:
Next, they create a folder at the root of the plugin with the same name as the namespace. In this case, com.github.copilot/. Inside that folder, they can place any Copilot-specific content, including an agents folder with one or more agent definitions. That paths entry tells Copilot to load agents from the extension’s agents folder. The same extension directory can contain other Copilot-only functionality, including hooks and Language Server Protocol (LSP) server definitions. This allows those configurations to coexist with other vendors’ extensions without conflict. It also means that vendors can use this format and add new features without waiting for a new version of the core specification.
This boundary is valuable even when Copilot is your only target today. It makes the dependency explicit: the release skill can travel, but the specialized agent orchestration requires Copilot. A future compatible client can still use the skill and MCP server without pretending it understands the agent definition.
Migrating a preview-era plugin
Existing Copilot plugins remain supported, so there is no reason to rush a migration. For new work, though, use the 1.0 layout. It is a straightforward conversion:
- Make sure
plugin.jsonis in the plugin root and add the 1.0 schema URL. - Place portable skills below
skills/and MCP configuration in root-levelmcp.json. - Move custom and related Copilot behavior below
com.github.copilot/. - Add extension entries for any Copilot directories that need to be discovered, such as
agents.paths. - Test in each intended client.
The GitHub announcement describes the same migration direction: standardize the shared pieces, then place Copilot-specific additions in the namespace that owns them. It is an evolutionary change, not a rewrite of your useful content.
To make the plugin discoverable, you can also add a marketplace.json file that provides details about the available plugins and their location. This allows you to aggregate plugins whether they live in one repository or across multiple repositories. The
Copilot CLI docs provide a full description of the marketplace.json format.
A clearer future for plugins
Agent Plugins finally create a defined compatibility story for plugins that allows them to work more consistently across AI clients while still supporting the rich features each client has to offer. At the same time, it makes it easier for vendors to structure private features without creating compatibility issues for other clients. The specification is still evolving, but it is already a significant improvement over the earlier, client-specific formats. If you aren’t using it, I recommend starting to explore the format so you can see what it can do for you!