Agent Plugins: A Portable Standard for Agent Extensions

AI agent capabilities are often distributed as loose instructions, copied configuration, one-off scripts, and client-specific folders. That works for a single setup. It becomes harder when the same capability needs to be reviewed, versioned, installed, and used across different agent clients.

Agent Plugins proposes a small, open package format for that problem. Version 1.0.0 is currently a Working Draft. It defines how reusable agent extensions can be organized into a predictable directory with a manifest and optional components. A compatible client can inspect the package, discover the parts it supports, and handle each component through explicit rules.

The standard is intentionally focused. It packages capabilities; it does not prescribe a complete agent framework, marketplace, permission model, or user interface. That narrow scope is useful: plugin authors get a portable contract, while clients remain free to decide how capabilities are installed, authorized, and operated.

What Agent Plugins Standardizes

An Agent Plugin is a self-contained directory rooted at one filesystem location. Every plugin has a plugin.json manifest. Version 1 defines exactly two portable component types: Agent Skills and MCP server configuration.

The standard uses fixed locations rather than letting every package invent its own structure:

A plugin can contain only a manifest, only skills, only MCP configuration, or a combination. Missing optional locations are valid. Clients discover supported components independently, so one invalid optional component does not automatically invalidate everything else.

A complete package might look like this:

release-operations/
├── plugin.json
├── skills/
│   ├── prepare-release/
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   │   └── verify.sh
│   │   └── references/
│   │       └── checklist.md
│   └── rollback/
│       └── SKILL.md
├── mcp.json
├── com.example.client/
│   └── hooks.json
├── LICENSE
└── CHANGELOG.md

The predictable layout makes a plugin understandable before it is executed. Authors know where each portable component belongs, and clients know where to look without relying on custom setup instructions.

plugin.json: The Package Contract

The root manifest is the entry point. Its required $schema value selects the Agent Plugins version and its validation rules. The required name identifies the package. Metadata such as version, description, author, homepage, repository, license, and keywords supports discovery and maintenance.

A small conforming manifest looks like this:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "release-operations",
  "version": "1.0.0",
  "description": "Skills and tools for controlled software releases",
  "repository": "https://github.com/example/release-operations",
  "license": "MIT",
  "keywords": ["release", "deployment", "operations"]
}

The manifest schema is closed: portable top-level fields come from the specification. Client-specific settings belong under extensions, where reverse-domain namespaces prevent collisions. Components themselves remain in their fixed locations; skills and MCP configuration are not embedded inside plugin.json.

This separation keeps the manifest compact. It describes the package and points clients toward a stable contract without turning one JSON file into an unstructured container for every possible integration.

Skills Package Repeatable Agent Knowledge

Skills are the instruction layer of an Agent Plugin. Each immediate child of skills/ that contains a SKILL.md is discovered as one skill. The skill document follows the independent Agent Skills specification, which defines its frontmatter, instructions, and supporting directory conventions.

A skill can include additional material beside SKILL.md:

• scripts/ for executable helpers.
• references/ for documentation loaded when needed.
• assets/ for templates and other output resources.

That makes a skill more than a long prompt. It can package a repeatable workflow with focused instructions, reference material, and deterministic helpers. A release plugin, for example, might provide one skill for preparing a release and another for performing a rollback review.

Clients still control how skills are presented to agents or users. The Agent Plugins standard defines discovery and validation; the Agent Skills standard defines the skill format. Together they give authors a reusable instruction package without dictating the entire client experience.

mcp.json Packages Tool Connections

Agent Plugins uses root-level mcp.json for optional Model Context Protocol server configuration. The MCP specification defines protocol behavior and lifecycle. Agent Plugins defines the portable configuration file a client can map into its own MCP setup.

The document has its own required schema and an mcpServers object:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "release-validator": {
      "type": "stdio",
      "command": "./bin/validator",
      "args": ["--data", "${PLUGIN_DATA}/validator"],
      "cwd": "${PLUGIN_ROOT}"
    },
    "deployment-api": {
      "type": "streamable-http",
      "url": "https://deploy.example.com/mcp"
    }
  }
}

Version 1 defines stdio, streamable-http, and legacy sse server variants. A client supporting plugin MCP servers must support at least one of stdio or streamable-http, and the specification recommends supporting both.

For local servers, the client supplies two reserved paths. PLUGIN_ROOT points to the installed package, while PLUGIN_DATA points to persistent, client-managed data for that plugin instance. This lets a package reference bundled files and durable generated state without hard-coding machine-specific absolute paths.

Credentials remain a client responsibility. Plugin environment values and HTTP headers are visible package data, so the specification does not treat them as a portable secret store. Authorization discovery, user interaction, and secure credential storage belong to the client that creates the connection.

Extensions Preserve Portability Without Blocking Clients

A portable core cannot anticipate every client capability. Agent Plugins handles that through reverse-domain extension namespaces.

A client can place structured settings under extensions in plugin.json, add a top-level directory with the same namespace, or use both:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "release-operations",
  "extensions": {
    "com.example.client": {
      "manifest": "client.yaml"
    }
  }
}

Clients that recognize com.example.client can apply its rules. Other clients ignore that namespace and continue loading the portable components they support. The result is a stable core with room for native installation metadata, hooks, interface definitions, or lifecycle configuration.

Failure Isolation Is Part of the Format

A good plugin format needs predictable failure boundaries. Agent Plugins separates manifest validity, skills, MCP configuration, and individual MCP server entries.

• An invalid required manifest rejects the plugin.
• An invalid skill is skipped while other skills and component types can continue loading.
• An invalid mcp.json disables MCP for that plugin without discarding valid skills.
• An invalid or unsupported MCP server entry is skipped independently.
• A server connection or authentication failure does not prevent other components from loading.

The specification also requires plugin-supplied paths to remain inside the plugin root. Clients resolve and validate paths, reject escapes, and keep PLUGIN_DATA under a dedicated client-managed location. These rules create a safer and more diagnosable package boundary, although they do not replace the client’s runtime sandbox, permission system, or operator approval model.

Apteva Supports the Agent Plugins Standard

Apteva supports the open Agent Plugins 1.0.0 package layout alongside its native Apps contract. An Apteva App can ship plugin.json, portable skills, optional mcp.json, and its existing apteva.yaml manifest in the same package. The portable manifest selects the native manifest through Apteva’s extension namespace:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "crm",
  "version": "0.8.24",
  "extensions": {
    "com.apteva": {
      "manifest": "apteva.yaml"
    }
  }
}

Other compatible clients can ignore com.apteva and consume the portable components they support. Apteva follows the extension to apteva.yaml, which remains authoritative for App installation, project scope, permissions, credentials, routes, UI, workers, events, data, and lifecycle.

Today, Apteva acts as an Agent Plugins Skills client. Source installs discover canonical skills/*/SKILL.md files and merge them with native App skills. Native declarations win duplicate names, so a package cannot silently replace an established App skill contract. Invalid optional plugin components are isolated and reported without preventing a healthy native App from starting.

The Apteva App SDK also parses and validates Agent Plugins manifests and portable mcp.json entries for package authors. Installed App tools continue to run through Apteva’s authenticated, installation-scoped native MCP bridge. That is why the CRM reference package includes plugin.json and a portable CRM skill but deliberately omits mcp.json: its MCP URL, authorization, project identity, and installation identity are assigned during installation rather than published as portable constants.

The implementation details and Go APIs are documented in the Apteva App SDK compatibility guide. The standard itself remains the source of truth for portable package behavior, with development taking place in the Agent Plugins specification repository.

A Small Standard With a Useful Job

Agent Plugins gives agent capability authors a concrete distribution unit: one manifest, fixed component locations, portable skills, optional MCP server configuration, and namespaced client extensions. It makes packages easier to inspect, validate, version, and support across compatible clients.

Apteva supports that standard while providing the broader framework in which agents, Apps, workers, events, memory, schedules, dashboards, and integrations operate together. Package the reusable capability once, then run it inside an environment that owns the operational context.

Explore Apteva on GitHub or read the Agent Plugins 1.0.0 specification to start building a compatible package.