What Is an Agent Plugin? How to Package AI Skills

What Is an Agent Plugin? It is a directory package for bundling extensions for AI agents, primarily Agent Skills and MCP server configuration. Instead of copying the same skill into each tool using a different structure, you prepare a standard directory containing plugin.json, a skills/ directory, and an optional mcp.json. Applications that support the standard can read and load these components according to the same rules. Agent Plugins 1.0.0 currently defines two portable component types—skills and MCP servers—not a complete AI runtime or a universal plugin marketplace (according to the Agent Plugins Specification).

The format’s main value is AI interoperability. You must still verify whether each client supports the standard, MCP transport, and its authorization model; a valid plugin does not automatically run identically across every tool.

What Is an Agent Plugin, and What Problem Does It Solve?

In practice, an AI agent often needs two types of extensions. The first is a skill: instructions for workflows, criteria, output formats, or document use. The second is a tool: a capability for accessing external systems such as databases, APIs, code repositories, or search services. An MCP server typically provides the second layer, while SKILL.md describes the first.

An Agent Plugin combines these two layers in a package with fixed file locations:

plugin.json: the required manifest in the root directory.
skills/: each direct subdirectory can contain a SKILL.md.
mcp.json: configuration for one or more MCP servers, if the plugin requires external tools.
An extension directory using a reverse-domain namespace, such as com.example.client/, is reserved for client-specific data.

The standard does not allow plugin.json arbitrary, self-defined paths for skills or MCP. The client must look for skills in skills/ and MCP configuration in mcp.json. If an optional location is absent, that is not an error; a plugin may contain only skills or only MCP servers (according to the Agent Plugins component-discovery rules).

The key distinction is that an Agent Plugin does not replace MCP. MCP still defines how clients and servers communicate, connection lifecycles, and tool provision. Agent Plugins only define the packaging format and tell clients where to find MCP configuration.

If you operate a blog or website and want content that AI agents can easily read and use, see the AI-agent blog optimization checklist to address structure, data, and retrievability at the source.

Agent Plugins 1.0.0 Structure and Packaging

1. Create the plugin.json Manifest

In Agent Plugins 1.0.0, plugin.json must be a JSON object in the root directory. The two required fields are $schema and name. Fields such as version, description, author, homepage, repository, license, keywords and extensions are optional.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "content-audit",
  "version": "1.0.0",
  "description": "Kiểm tra cấu trúc và chất lượng nội dung blog",
  "author": {
    "name": "Example Studio"
  },
  "license": "MIT",
  "keywords": ["seo", "content", "audit"]
}

The value of name must be 1–64 characters long and use only lowercase letters, digits, hyphens, or periods; it must not begin or end with a separator and must not use the strings -- or ... This is a common error that causes the manifest to be rejected even when the JSON syntax is valid (according to the Agent Plugins 1.0.0 manifest rules).

2. Add a Skill to skills/

Each skill must be placed in a direct subdirectory of skills/. For example:

content-audit/
├── plugin.json
├── skills/
│   └── seo-review/
│       ├── SKILL.md
│       ├── references/
│       │   └── checklist.md
│       └── scripts/
│           └── check-links.py
└── mcp.json

The client does not search recursively without limit. Therefore, placing SKILL.md at skills/seo-review/SKILL.md is correct, whereas placing it deeper, such as skills/seo-review/docs/SKILL.md , may prevent the skill from being discovered. The contents and frontmatter of SKILL.md must comply with the Agent Skills specification; the skill name in the frontmatter should match the directory name to avoid routing errors (according to the Agent Skills Specification).

Write the skill description in terms of “when to load this skill” rather than merely describing its subject. For example: “Load when you need to review a blog post’s title, internal links, and structured data.” This helps the agent choose the right time to load the skill and reduces the loading of irrelevant instructions.

3. Declare the MCP server in mcp.json

If the skill needs to call external tools, create mcp.json in the root directory:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "local-audit": {
      "type": "stdio",
      "command": "./bin/audit-server",
      "args": ["--data", "${PLUGIN_DATA}/audit"],
      "cwd": "${PLUGIN_ROOT}"
    },
    "remote-search": {
      "type": "streamable-http",
      "url": "https://example.com/mcp"
    }
  }
}

For stdio, command must be an executable token, not a shell command string such as node server.js && echo done. Relative paths must begin with ./. The ${PLUGIN_ROOT} and ${PLUGIN_DATA} variables are useful for distinguishing fixed packaged files from generated data that must persist after a plugin update.

Do not place API keys or passwords in env, headers, source code, or the manifest. Agent Plugins 1.0.0 does not define a portable secret-storage mechanism; authentication, OAuth, and credential management are the client’s responsibility. This is an important security limitation: “usable across multiple tools” does not mean “sharing a single authorization mechanism.”

4. Package, validate, and release

Create the plugin directory with the correct name and structure.
Validate the JSON with a parser before pushing it to Git.
Compare $schema in plugin.json and mcp.json; the two versions must match.
Validate each SKILL.md, especially the frontmatter, directory names, and referenced file paths.
Test it on each target client, including cases where the MCP server is unavailable or the credentials are incorrect.
Clearly document the installation requirements, environment variables, access permissions, and supported transport in the README.

A practical way to verify the result is to ask the agent to list the loaded skills, check whether the MCP server has completed its handshake, and then run a small task that can be verified manually. If MCP fails, the skill should still be loaded; the specification requires the client to continue loading the other components rather than breaking the entire plugin.

Limitations, common errors, and effective use

First, not every client is fully compatible. A client may be able to read skills but not yet support MCP, or support only stdio without supporting streamable-http. Publish a compatibility matrix instead of claiming that the plugin runs on every tool.

Second, a plugin is not a sandbox. Path rules help the client prevent references from escaping the plugin directory in the cases covered by the specification, but they do not automatically restrict every behavior of an MCP process. You still need to assess the source code, operating-system permissions, third-party dependencies, and the data the server may access.

Third, do not put all the logic into the skill. A skill should contain procedures and decision criteria; the MCP server should provide operations or data through a clear interface. If a SKILL.md is both long, full of frequently changing information, and descriptive of dozens of tools, the agent will be harder to route and maintain.

Fourth, do not use arbitrary top-level fields in plugin.json. Client-specific data should be placed in extensions with a stable namespace, such as com.example.client. Other clients will ignore namespaces they do not implement, reducing conflicts between ecosystems.

For websites, documenting the author, area of expertise, and content responsibilities is also important when agents evaluate a source. You can also see how to create an author page for a blog to strengthen trust signals before packaging content as a skill.

Finally, manage the plugin version independently of the specification version. Agent Plugins 1.0.0 is the format version; the version field in plugin.json is the plugin’s own version. When changing behavior, an MCP endpoint, or installation requirements, update the changelog and describe the impact so users know whether they need to reconfigure anything.

Conclusion: Agent Plugin is well suited to distributing a structured AI skill, optionally accompanied by MCP server tools, through a unified directory. The safest process is to start with a minimal manifest, add one small skill, test it on the target client, and only then add MCP and other extensions. The standard improves AI interoperability at the packaging layer, while leaving the client to determine how the plugin is installed, authorized, displayed, and executed.

If you are optimizing content so that multiple AI systems can understand and use it, combine the plugin with guidance on optimizing a blog for AI Overviews and AI ModeThese address two different layers: the plugin standardizes an agent’s components, while SEO makes the content source easier to discover.

What Is an Agent Plugin? Package AI Skills Across Tools