MCP HubMCP Hub
POST·BUILDY

如何构建你的第一个智能体插件：分步指南

AIMCP Teamon 19 days ago · 1 min read

如何构建你的第一个智能体插件：分步指南

智能体插件（v1.0.0）是智能体组件（技能与MCP服务器）的便携式打包标准，可在兼容客户端间通用。本指南将带你从零构建一个真实且符合规范的插件：一个包含一项技能和一个MCP服务器的插件，并依据官方模式进行验证。

步骤一：创建包结构

插件本质上就是一个目录。首先创建包含两个必需组件的结构：

my-plugin/
├── plugin.json
├── skills/
│   └── summarize/
│       └── SKILL.md
└── mcp.json

步骤二：编写清单文件

plugin.json 是唯一必需的文件。清单模式是封闭的——可移植的顶层字段仅限于固定集合：

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "summarize.tools",
  "version": "1.0.0",
  "description": "用于文档摘要的技能和服务器。",
  "author": {
    "name": "你的名字",
    "url": "https://example.com"
  },
  "homepage": "https://example.com/summarize-tools",
  "repository": "https://github.com/you/summarize-tools",
  "license": "MIT",
  "keywords": ["summarization", "documents", "llm"]
}

只有 $schema 和 name 是必需的。其他字段均为可选但建议填写：version（遵循语义化版本）、description、author、homepage、repository、license（SPDX格式）以及用于发现的 keywords。

注意： 该模式设计为封闭式。客户端特定的设置应放在扩展命名空间中，而非顶层字段。

步骤三：添加技能

技能位于 skills/ 目录下，遵循智能体技能规范。每个直接包含 SKILL.md 文件的子目录即代表一项技能：

skills/
└── summarize/
    ├── SKILL.md
    ├── scripts/
    │   └── summarize.py
    └── references/
        └── guidelines.md

一个最简化的 SKILL.md 示例：

---
name: summarize
description: 将文档摘要为关键要点。当用户要求压缩长文本时使用。
---

# 摘要功能

1. 从用户输入中读取文档。
2. 提取主要论点、支持点和行动项。
3. 以Markdown格式撰写摘要，最多10个要点。

## 脚本

- `scripts/summarize.py` —— 接收文件路径并输出摘要的命令行工具。

客户端通过扫描 skills/*/SKILL.md 来发现技能；它们不会深入递归扫描，因此请确保每个直接子目录仅包含一项技能。

步骤四：添加MCP服务器

如果你的插件包含MCP服务器，请在 mcp.json 中描述它。该格式支持标准输入输出、可流式HTTP及传统的HTTP+SSE传输方式：

{
  "servers": {
    "summarize": {
      "command": "python",
      "args": ["scripts/mcp_server.py"],
      "env": {}
    }
  }
}

客户端会将此便携格式映射到其原生配置——字段名称无需与任何客户端的内部格式匹配。

步骤五：（可选）添加客户端扩展

是否想为特定客户端添加功能而无需修改核心部分？使用以你客户端命名的反向域名命名空间目录，例如 com.example.client/hooks/hooks.json。客户端会在插件根目录查找其命名空间目录；未知的命名空间将被忽略。

步骤六：验证

在分发之前，请验证你的清单：

  1. $schema 必须引用官方模式URL：https://agent-plugins.org/schemas/1.0.0/plugin.schema.json。
  2. name 必须存在且非空——缺少必需字段会导致整个插件无效，客户端必须拒绝加载。
  3. 检查你的 SKILL.md 前置元数据是否至少包含 name 和 description。
  4. 根据规范中的JSON模式（发布于 agent-plugins.org/schemas）验证 mcp.json。

你也可以使用规范仓库的示例插件（agentplugins/agent-plugins-example）作为标准参考，或通过AIMCP的目录提交功能运行你的插件——它会根据官方模式进行验证并报告组件数量。

步骤七：分发

智能体插件是一个目录，因此分发方式非常灵活：可以推送到GitHub仓库、发布到市场或直接分享。无论通过何种方式传输，兼容的客户端都能一致地发现并加载插件。

后续步骤