一个可复制的代理插件规范 v1.0.0 参考包。

该仓库展示了可移植核心，并包含一个代理技能，帮助将现有插件从客户端特定格式迁移。这是一个参考示例，而非规范规范的替代品;如果它们存在差异，规范将占优。

布局

最小的有效插件只需 plugin.json。这个示例包含一个技能，因此既实用又具有结构说明意义。

便携核心

Agent Plugins v1 定义了两种可移植组件类型：

• Agent Skills，隶属于skills/的直接子目录。
• MCP服务器在可选的根mcp.json中，使用匹配的v1.0.0 MCP模式。

根 plugin.json 模式已关闭。不要在其顶层添加 hooks、agents、commands、mcpServers、lspServers 或任意客户端字段。将可移植式 MCP 配置放入 mcp.json，客户端拥有的清单数据置于 extensions。

请参阅权威文档，包括插件清单、技能、MCP服务器和客户端扩展。

安全添加客户专属功能

钩子和类似功能不是移植版 v1 组件。

Agent Plugins Example

A copyable reference package for the Agent Plugins Specification v1.0.0.

This repository demonstrates the portable core and includes an Agent Skill that helps migrate existing plugins from client-specific formats. It is a reference example, not a substitute for the normative specification; if they differ, the specification wins.

Layout

agent-plugins-example/
├── plugin.json                         # Required portable manifest
├── skills/                             # Portable Agent Skills
│   └── migrate-agent-plugin/
│       ├── SKILL.md
│       └── references/
│           ├── client-extensions.md
│           ├── migration-guide.md
│           └── validation-checklist.md
├── README.md
└── LICENSE

The smallest valid plugin needs only plugin.json. This example includes a skill so it is useful as well as structurally illustrative.

The portable core

Agent Plugins v1 defines two portable component types:

• Agent Skills under immediate child directories of skills/.
• MCP servers in an optional root mcp.json using the matching v1.0.0 MCP schema.

The root plugin.json schema is closed. Do not add hooks, agents, commands, mcpServers, lspServers, or arbitrary client fields at its top level. Put portable MCP configuration in mcp.json and client-owned manifest data inside extensions.

See the authoritative documentation for the plugin manifest, skills, MCP servers, and client extensions.

Add client-specific capabilities safely

Hooks and similar capabilities are not portable v1 components. A client can add them through a reverse-domain extension namespace it owns and documents:

your-plugin/
├── plugin.json
├── skills/
├── mcp.json                            # Optional portable MCP configuration
└── com.vendor.client/                  # Optional client extension
    └── hooks/
        └── hooks.json

If a client uses both manifest data and files, plugin.json can contain an extension object:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "your-plugin",
  "extensions": {
    "com.vendor.client": {
      "settingDefinedByThatClient": true
    }
  }
}

com.vendor.client is illustrative. Use only a namespace and fields documented by the client that owns them. Other clients ignore an extension they do not implement, leaving the portable skills and MCP configuration usable.

Migrate without breaking the existing plugin

Use an additive migration:

1. Add and validate the root plugin.json without deleting working platform files.
2. Move or copy reusable skills into skills//SKILL.md.