AI Agent - Aug 9, 2026

Agent Plugins 1.0 Specification Guide

Quick answer

Agent Plugins 1.0.0 defines a small, vendor-neutral package format for two portable component types: Agent Skills and MCP servers. A package is a directory with plugin.json at its root, optional skills in skills/, optional MCP configuration in mcp.json, and optional client-owned extension namespaces.

The live normative document labels version 1.0.0 a Working Draft. It defines packaging, discovery, validation, containment, failure boundaries, and client conformance. It does not define installation, distribution, permissions, subprocess sandboxing, trust, provenance verification, or approval UX.

The portable directory contract

my-plugin/
├── plugin.json
├── skills/
│   └── summarize/
│       ├── SKILL.md
│       ├── scripts/
│       └── references/
├── mcp.json
└── com.example.client/

Only the first file is required. A plugin can contain skills, MCP servers, both, or neither. Missing optional component locations do not invalidate the manifest.

The fixed locations are deliberate. plugin.json cannot move components or declare them inline. A client discovers immediate child skills under skills/ and reads MCP configuration only from root mcp.json.

plugin.json is a closed manifest

The minimum manifest identifies a supported schema and plugin name:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "my-plugin"
}

The v1 schema permits a defined set of top-level metadata fields, including version, description, author, homepage, repository, license, keywords, and extensions. Most schema violations are fatal. Unknown top-level fields are a narrow exception: clients report and ignore them, then continue if the rest of the manifest is valid. Client-specific data belongs under extensions, not in new portable top-level fields.

Clients select locally supported validation rules from $schema; they do not fetch a remote schema while loading the plugin. A published canonical schema identifier cannot be reassigned to different contents.

Skills stay Agent Skills

Agent Plugins does not redefine SKILL.md. Each immediate child of skills/ with a regular file named exactly SKILL.md is a discovered skill, and the separate Agent Skills specification remains the source of truth for its format.

Discovery is not recursive. An invalid skill is skipped without disabling valid sibling skills or independent MCP configuration. This is an example of the specification’s narrow failure boundaries.

MCP servers stay MCP

The Model Context Protocol defines wire behavior and lifecycle. Agent Plugins defines the portable mcp.json configuration that tells a compatible client how to locate and connect to servers.

For v1.0.0, mcp.json uses its own canonical schema identifier and an mcpServers object. Each entry declares one explicit transport:

  • stdio for a local executable token plus separate arguments, environment, and working directory;
  • streamable-http for the current remote HTTP transport;
  • optional legacy sse for MCP’s deprecated HTTP+SSE transport.

A remote non-loopback endpoint must use HTTPS. Package-configured headers are visible data, not a portable secret mechanism. V1 defines no OAuth configuration or portable credential reference; authorization discovery, user interaction, and credential storage are client-managed.

If one MCP entry is invalid, unsupported, fails to start, cannot authenticate, or cannot complete the handshake, the client skips that entry and continues with other entries and component types.

Containment is not sandboxing

Package files and defined package-relative paths must remain within the filesystem-resolved plugin root. Clients account for symlinks, junctions, reparse points, and equivalent mechanisms. Stdio MCP working directories can also use the client-managed PLUGIN_DATA root where allowed.

This protects package resolution. It does not constrain what a launched process can access through its operating-system identity, network, inherited environment, tools, or runtime input. A compatible client still needs permission review, process isolation, secret controls, network policy, user confirmation, and monitoring.

Client extensions preserve a small core

A client can define additional data under a reverse-domain namespace in plugin.json.extensions, a top-level directory with the same namespace, or both. Other clients ignore namespaces they do not implement.

Commands, hooks, agents, or other client features can live there, but they are not portable Agent Plugins v1 components. A package can carry them without claiming that every compatible client understands them.

What a conformant client must do

At a high level, a conformant client:

  1. Loads from a directory and validates root plugin.json against a locally supported schema.
  2. Enforces package containment and the documented narrow failure boundaries.
  3. Discovers each supported component at its fixed location.
  4. Supports at least one of skills or MCP servers.
  5. If it supports MCP, implements at least stdio or Streamable HTTP and applies the matching configuration rules.
  6. Ignores unsupported component types and unimplemented client extensions.

Conformance does not mean every client exposes, approves, installs, or runs the same components in the same way.

Evaluation checklist

  • Pin $schema to the intended spec version in both JSON files.
  • Validate the closed manifest and each component independently.
  • Resolve filesystem paths before enforcing containment.
  • Keep command as one executable token and arguments separate.
  • Never embed credentials in package headers, manifests, examples, or source.
  • Document which transport and component types each target client supports.
  • Review installation source, signatures or provenance, permissions, sandbox, update policy, and rollback outside the v1 conformance check.

Compare the layers in Agent Plugins vs Agent Skills vs MCP, then follow the manifest, skills, and MCP authoring guide. For current Google adoption, see Agents CLI and Data Agent Kit.

Frequently asked questions

What does Agent Plugins 1.0 standardize?

It standardizes a directory package with a root manifest, fixed skills and MCP locations, optional namespaced client extensions, and compatible-client discovery and validation rules.

Is Agent Plugins 1.0 a final standard?

The normative specification identifies version 1.0.0 and labels its status Working Draft. Pin the schema version and recheck the live specification.

Does Agent Plugins sandbox an MCP server?

No. Package path containment is not process sandboxing and does not restrict runtime-supplied paths.

Does a valid plugin package prove that it is safe to install?

No. Installation, distribution, permissions, sandboxing, trust, provenance, and UX remain client and organization responsibilities.

Official sources

Source check: August 9, 2026. Recheck specification status, canonical schemas, compatible clients, transport support, failure handling, and security policy before shipping a package.