Agent Plugins Explained: How plugin.json, SKILL.md, and mcp.json Work Together

An agent plugin can contain useful instructions and tools, but packaging them inconsistently makes the experience harder to share across clients. One project may keep reusable instructions in a SKILL.md file, expose actions through an MCP server, and still need a separate wrapper for each client.

Agent Plugins v1.0.0 gives that package a shared structure. In this guide, you'll see what plugin.json, skills/, and mcp.json each do, where they belong, and how to validate a plugin before distributing it.

What is the Agent Plugins specification?

Agent Plugins is a packaging format for distributing reusable AI-agent components in a predictable directory. Version 1.0.0 is published, and its core portable component types are Agent Skills and MCP servers. It standardizes how a compatible client discovers those components; it does not replace the Agent Skills format or the MCP protocol itself.

Think of the layers this way: a skill supplies reusable instructions and resources; an MCP server exposes callable tools or data; the plugin package brings those components together so a compatible client can discover them consistently.

The three files and folders to understand

• plugin.json — the required manifest at the plugin root. It identifies the plugin and declares the manifest schema version.
• skills/ — the fixed location for skills. Each immediate child directory that contains a valid SKILL.md can represent a skill, with optional supporting scripts, references, or assets.
• mcp.json — the fixed location for MCP server configuration. It declares the servers and the transport each server uses.
• An optional client-specific extension directory can hold integrations owned by that client, using a reverse-domain namespace such as com.example.client/.

These locations are part of the specification, not arbitrary naming conventions. A client should not need to guess where your skills or server configuration live.

What belongs in plugin.json?

For Agent Plugins 1.0.0, the manifest must be a JSON object with the canonical $schema value and a valid name. Optional metadata can include a version, description, author, homepage, repository, license, keywords, and client-specific extensions.

The name has format rules: it must be 1–64 characters, use lowercase letters, digits, hyphens, or periods, start and end with an alphanumeric character, and avoid repeated hyphens or periods. For example, acme-research is valid, while Acme-Research uses uppercase letters and does not conform.

Use the canonical schema identifier for version 1.0.0: https://agent-plugins.org/schemas/1.0.0/plugin.schema.json. Keep MCP server definitions out of plugin.json; the specification assigns them to mcp.json.

How mcp.json connects an MCP server

The root mcp.json file contains the required $schema and mcpServers fields. Each server entry must explicitly declare a transport type and fields that match that transport.

• stdio is for launching a local executable. The entry uses a command and may include arguments, environment settings, or a working directory.
• streamable-http connects to a remote MCP endpoint using its URL.
• sse refers to the legacy HTTP+SSE transport. Support is optional for clients, so check the compatibility requirements of your target client before relying on it.

The v1.0.0 specification requires the corresponding schema identifier: https://agent-plugins.org/schemas/1.0.0/mcp.schema.json. Each server entry must match one of the documented variants; mixing fields from different variants can make that entry invalid.

Do not package secrets in the manifest

Treat the plugin directory as distributable package data, not a secret store. Do not commit API keys, bearer tokens, passwords, or private credentials into mcp.json. The Agent Plugins specification explicitly says configured headers are package data and are not a portable credential mechanism. Use the client’s supported authentication and secure credential storage instead.

Also review local paths carefully. Plugin-relative paths must use the required form and remain inside the plugin root. A path that escapes the package with ../ can violate the specification’s containment rules. These checks protect package layout, but they do not sandbox a process launched by the plugin.

A practical validation checklist

• Validate plugin.json against the v1.0.0 manifest schema and check its required fields.
• Validate mcp.json against the matching MCP configuration schema.
• Confirm every skill is in skills/<skill-name>/SKILL.md and follows the Agent Skills format.
• Check each MCP server’s type and confirm its required fields match that transport.
• Remove credentials from tracked files, sample configs, screenshots, and logs.
• Install the package in each intended client and test discovery, skill activation, tool calls, invalid arguments, and expected error cases.
• Keep client-specific features in the appropriate extension namespace instead of adding custom top-level fields to the portable manifest.

Common mistakes that break plugin discovery

• Putting everything in plugin.json. The manifest is not a place to inline skills or server definitions; keep components at their specified locations.
• Assuming every client supports the format. Client implementations can differ. Test each target client rather than treating a valid package as proof of universal support.
• Using a client-native MCP config unchanged. Agent Plugins defines a portable mcp.json format with explicit transport types. Translate configuration deliberately instead of copying fields blindly.
• Shipping secrets in headers. Package files can be shared or inspected. Store credentials through the client’s approved authentication flow.
• Validating JSON but not behavior. A file can parse correctly and still point to a missing executable, an unsupported transport, or an unreachable endpoint. Test the installed package.

When should you use Agent Plugins?

Use the format when you want to distribute a repeatable bundle of skills and MCP servers across clients that support it. It is especially useful when separate copies of the same components are drifting between developer machines or teams. If you only need one local MCP server in one client, a full plugin package may add little value.

The important distinction is that a valid manifest helps clients discover the package; it does not guarantee that a server will start, credentials will work, or every client will expose each feature the same way. Validate the package and run it in the actual client environment.

For the related server-configuration step, use the ManifestKit MCP Manifest Generator to prepare a cleaner server configuration, then validate the surrounding plugin files against the official v1.0.0 specification.

Further reading

Agent Plugins Specification v1.0.0 — the normative packaging rules, paths, manifest fields, and MCP configuration format.

Google Developers Blog: Agent Plugins package your skills, tools, and more — background on why a common package layout matters.

MCP Tools specification — how MCP tools are described, listed, called, and validated.

Frequently asked questions

What is Agent Plugins 1.0.0?

It is a published specification for packaging reusable agent components with a standard manifest and fixed component locations. Version 1 defines skills and MCP servers as its two portable component types.

Does plugin.json contain MCP server settings?

No. The root plugin.json is the portable plugin manifest. MCP server settings belong in the root mcp.json file, with its own schema identifier and explicit server transport types.

Can one plugin include both a skill and an MCP server?

Yes. A package can include skill directories under skills/ and server configuration in mcp.json. A compatible client discovers each component from its specified location.

Will one Agent Plugin work in every AI coding client?

Not necessarily. Support varies by client and version. Check the target client’s documented support and test the package’s discovery, authentication, and runtime behavior before distributing it.