创建插件与组件布局

先决定插件是否需要跨客户端复用。Agent Plugins 提供固定的可移植 Skills / MCP 结构；legacy 格式支持 Copilot 自定义组件路径。两者仍受支持，不能把字段混在同一 manifest 中。

Agent Plugins manifest

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "team-dev-tools",
  "version": "1.0.0",
  "description": "Shared development skills and tools",
  "license": "MIT"
}

放在插件根的 plugin.json。当前参考识别 1.0.0 和 1.1.0 的 canonical schema URL；不支持的 Agent Plugins 版本会拒绝整个插件，不回退 legacy，也不加载其任何组件。没有这些 schema 标识的普通 manifest 使用 legacy 语义。

Agent Plugins name 长度 1–64，只含小写 ASCII 字母、数字、连字符和点，首尾为字母数字，不允许连续 -- 或 ..。允许的顶层字段为 $schema、name、version、description、author、homepage、repository、license、keywords、extensions；未知字段会报告并忽略。

固定目录

team-dev-tools/
├── plugin.json
├── skills/
│   └── change-review/
│       └── SKILL.md
├── mcp.json
└── com.github.copilot/
    ├── agents/
    ├── commands/
    ├── rules/
    ├── hooks/
    │   └── hooks.json
    └── lsp.json

Skills 必须位于 skills 的直接子目录，不能用根 SKILL.md 后备。MCP 固定为根 mcp.json，并声明与 plugin.json 相同版本的 MCP schema。Copilot 专有组件位于 com.github.copilot，不表示其他客户端也支持它们。

extensions 在这种 manifest 中是按 reverse-domain namespace 分组的客户端数据，不是 legacy 中的扩展目录路径。

MCP 的路径变量

Agent Plugins MCP 支持 stdio、streamable-http、sse。stdio 子进程得到 PLUGIN_ROOT 与 PLUGIN_DATA，并在 args、env 值、cwd 中展开对应占位符。PLUGIN_DATA 是插件独立的可写持久目录，适合运行数据，避免写安装缓存。

远程 MCP 配置值按字面传递，不进行这类环境变量或占位符展开。插件内 agent 自己的 mcp-servers 另有有限规则：可展开 PLUGIN_ROOT 及兼容别名，但不扩大到 PLUGIN_DATA 或服务器环境变量，不能套用共享 MCP 的全部行为。

Legacy 格式

不声明 Agent Plugins schema 时，可以使用 agents、skills、commands、hooks、mcpServers、lspServers 等组件路径字段。agents / skills 可为一个路径或路径数组；hooks、MCP、LSP 可引用配置文件或内联对象。

例如：

{
  "name": "team-dev-tools",
  "agents": "agents/",
  "skills": ["skills/", "extra-skills/"],
  "hooks": "hooks.json",
  "mcpServers": ".mcp.json"
}

legacy manifest 查找顺序是 .plugin/plugin.json、根 plugin.json、.github/plugin/plugin.json、.claude-plugin/plugin.json；根目录有效 Agent Plugins manifest 优先于兼容位置。建议只保留明确的一份，避免误读格式。

验证与迭代

运行 copilot plugin install ./my-plugin 和 copilot plugin list，再在会话里用 /agent、/skills list、/mcp list 检查组件。直接本地安装会缓存，改动后重装。最后按 manifest name 卸载测试安装。

不仅检查“插件出现在列表”，也要实际验证每类组件：同名 Skills / Agents 可能被项目或个人来源遮蔽，MCP 则可能覆盖低优先级定义，详见项目 MCP 优先级。