How to Build Portable Tools With Agent Plugins 1.0.0

On August 6, 2026, a coalition including Google, Microsoft, OpenAI, and Vercel launched the Agent Plugins 1.0.0 specification. This standard establishes a vendor-neutral directory layout for AI agent extensions, eliminating the need to maintain separate tool configurations for different coding assistants. By combining instructions and live data connections into a single portable directory, developers can build a plugin once and deploy it across environments like Cursor, GitHub Copilot, and the Google Agents CLI. Here is how to structure a compliant plugin, configure the required manifests, and declare your tool transports.

Directory Structure Overview

An Agent Plugin functions as a self-contained unit defined entirely by its folder structure and a root manifest. The 1.0.0 specification dictates strict locations for the core components while leaving room for client-specific additions.

A standard compliant plugin follows this hierarchy:

• plugin.json: The root manifest defining the plugin identity.
• skills/: The directory holding static instructions and prompt context.
• mcp.json: The declaration file for external tool connections.
• [reverse-domain]/: An optional directory for environment-specific hooks.

This structure ensures that any compliant client knows exactly where to look for capabilities without requiring a custom build step.

Configuring the Plugin Manifest

The root of your directory must contain a plugin.json file. This manifest serves as the entry point for the host client.

The specification requires two mandatory fields. The $schema key must point exactly to https://agent-plugins.org/schemas/1.0.0/plugin.schema.json. The name key must provide a unique identifier for your plugin. You can also include optional metadata like a version number or description to help users identify the package in their client interfaces.

When a host application loads your directory, it validates this manifest first. If the schema validation fails, the client will refuse to mount the tools.

Packaging Agent Skills

The skills/ directory handles the static capabilities and procedural knowledge your plugin provides. This folder adheres to the existing specifications for agent skills, organizing instructions into discrete, context-aware units.

Inside the skills/ directory, you create a subdirectory for each individual capability. Every subdirectory must contain a SKILL.md file. The SKILL.md file defines the trigger conditions, system prompts, and formatting rules the agent needs to execute that specific task.

Structuring skills in this manner allows clients to selectively load context. When a user asks their AI assistant to perform a task, the host client scans the skills/ directory and injects the relevant SKILL.md content into the model’s context window. This keeps the prompt budget low while maintaining high capability.

Declaring MCP Servers

While skills provide static instructions, dynamic tool execution and data retrieval rely on the Model Context Protocol. You define these connections in the mcp.json file located at the root of your plugin directory.

The mcp.json file lists all the external servers your plugin needs to communicate with. For each server, you must explicitly declare the transport type. The 1.0.0 specification officially supports stdio, Streamable HTTP, and legacy HTTP+SSE transports.

The stdio transport is typically used for local, sidecar processes running on the user’s machine, making it ideal for desktop IDE plugins. The Streamable HTTP transport connects to remote endpoints and is optimized for the stateless MCP core introduced on July 28, 2026. This stateless design is critical for plugins targeting cloud-native chat interfaces, as it allows the host client to scale connections horizontally without maintaining persistent session IDs.

Handling Client-Specific Extensions

The specification requires plugins to be portable, but developers often need to utilize advanced features specific to a single environment, such as a custom UI rendering hook in VS Code or a specialized command in the Google Data Agent Kit.

To accommodate this, the standard provides an escape hatch via reverse-domain directories. You can create a folder named using a reverse-domain format, such as com.google.agent/ or com.microsoft.vscode/, at the root of your plugin.

Inside these directories, you can place configuration files, scripts, or assets that only apply to that specific client. Compliant parsers are instructed to ignore any reverse-domain directories they do not explicitly own. This allows you to ship a single package that degrades gracefully across standard clients while offering enhanced functionality in targeted platforms.

Understanding Scope and Limitations

The Agent Plugins 1.0.0 specification focuses entirely on file structure and component discovery. It is critical to understand what the standard deliberately omits.

The specification does not define installation mechanisms, permission models, sandboxing strategies, or payment systems. A plugin that works perfectly in Cursor might face different security prompts or network restrictions when loaded into OpenAI’s ChatGPT.

You cannot rely on the plugin.json to enforce execution boundaries. Trust, provenance, and tool approval remain under the strict control of the host client’s marketplace or execution environment. When building your tools, you must design your MCP servers to handle authentication and authorization independently of the plugin manifest.

To begin testing your extensions, set up a local directory matching the spec and load it directly into a compatible client like the Google Agents CLI using the local development flags.