Skip to content

whale4rain/agent-plugins-example-zh

v0.1.0Apache-2.0

基于 Agent Plugins Specification v1.0.0 的中文实践示范仓库：通过高质量 Skill、MCP 及二者组合案例，展示 Agent Plugin 的设计、组织、运行与复用。

GitHub

Agent Plugins 中文实践示范仓库

基于 Agent Plugins Specification v1.0.0 构建的非官方中文实践与参考实现（Reference Examples）。

本项目不是官方规范的中文翻译，也不是 Skill / MCP 的资源堆砌，而是一个面向中文开发者的、可以实际运行与改造的示范仓库——重点演示 Skill、MCP，以及二者组合成的完整 Agent Workflow 应当如何设计、组织、运行与复用。

这个项目是什么

一个可复制的 Agent Plugin 参考包。它同时承担两层身份：

  1. 一个符合规范的 Plugin：根目录 plugin.json + skills/ + mcp.json，任何遵循 Agent Plugins v1 的客户端都可以加载。
  2. 一份实践教程：docs/ 讲清「为什么这么设计」，examples/ 演示「怎么组合成真实工作流」。
agent-plugins-example-zh/
├── plugin.json                      # 必需的封闭 manifest
├── mcp.json                         # 3 个社区标准 MCP server
├── skills/                          # 4 个高质量 Agent Skill
│   ├── go-code-review/
│   ├── go-performance-debug/
│   ├── github-issue-analysis/
│   └── zh-doc-analysis/
├── examples/                        # 3 个 Skill + MCP 组合案例
├── docs/                            # 学习文档
├── README.md
├── CHANGELOG.md
├── LICENSE                          # Apache-2.0
└── NOTICE                           # upstream attribution

为什么存在

中文开发者第一次接触 Agent Plugin 时，常见困惑是：规范能看懂，但不知道一个「好的」Plugin 长什么样，也不知道 Skill 和 MCP 到底该怎么分工、怎么组合。

本项目要回答的问题只有一个：

如何把 Skill、MCP 和真实开发工作流，组合成可复用、可运行、可维护的 Agent 能力？

因此它刻意不做：

  • ❌ 官方仓库的简单中文翻译
  • ❌ 大量 Hello World / Calculator / Weather 式 Skill
  • ❌ 只展示「能调用工具」的 MCP Demo 集合
  • ❌ 一个 Prompt 收藏夹
  • ❌ 未经验证却宣称 production-ready 的内容

它做的是：少而精、可运行、可解释、可复用。

快速开始

前置条件

  • 一个支持 Agent Plugins v1 的客户端（或任意能加载 plugin.json + skills/ 的环境）。
  • Node.js（MCP server 通过 npx 运行）。
  • （可选）一个 GitHub Personal Access Token，用于 github MCP 的认证。

运行

git clone https://github.com/whale4rain/agent-plugins-example-zh.git
cd agent-plugins-example-zh
  1. 阅读 docs/getting-started.md，理解 Plugin / Skill / MCP 三者关系。
  2. 挑选一个 Skill（如 skills/go-code-review/）直接使用。
  3. 按 docs/mcp.md 配置 MCP server（注意 secret 由客户端注入，不写入 mcp.json）。
  4. 按 examples/ 里的组合案例，运行一个完整的 Skill + MCP 工作流。

更详细的安装、配置、权限与安全说明见 docs/getting-started.md。

Examples 一览

Skill（4 个）

Skill解决什么问题目录
go-code-reviewGo 后端代码审查：goroutine 泄漏、data race、context、channel、mutex、错误处理、内存、SQL、Redis、可观测性skills/go-code-review/
go-performance-debugGo 服务 OOM / 性能问题定位与修复skills/go-performance-debug/
github-issue-analysis从 Issue 到根因、修复方案、测试方案的完整分析skills/github-issue-analysis/
zh-doc-analysis中文技术文档的架构、API、依赖、用法与潜在问题分析skills/zh-doc-analysis/

MCP（3 个，均引用社区标准 server）

MCP提供什么外部能力来源
githubGitHub Issue / PR / Commit / 代码检索@modelcontextprotocol/server-github
filesystem本地仓库文件的读取与写入@modelcontextprotocol/server-filesystem
fetch抓取远程文档 / 网页内容@modelcontextprotocol/server-fetch

组合案例（3 个）

案例Skill+MCP=
Go 后端调试go-performance-debug+filesystem + githubOOM 根因 + 修复 + 测试
GitHub Issue 根因分析github-issue-analysis+github + filesystemIssue → 根因 → 修复方案
中文文档研读zh-doc-analysis+fetch + filesystem文档 → 架构 → 用法 → 潜在问题

Skill / MCP / Plugin 的关系

这是本项目最想讲清的一层抽象：

                  Agent Plugins
                       │
             Specification / Model
                       │
          ┌────────────┴────────────┐
          │                         │
       Skill                       MCP
          │                         │
          └────────────┬────────────┘
                       │
                 Plugin Examples
  • Plugin：分发包单位（一个目录 + plugin.json），承载多个组件。
  • Skill：指导 Agent 怎么做——workflow、reasoning guidance、领域知识、指令与约束。它是「大脑」。
  • MCP：提供 Agent 能访问什么——数据、工具、API、仓库、数据库、运行时信息。它是「手脚」。

一个清晰的职责边界：Skill 负责思考，MCP 负责触达外部世界。 不要把 MCP 调用逻辑硬编码进 Skill，也不要把工作流塞进 MCP。

详细说明见 docs/skill-and-mcp.md。

Upstream 关系与许可

本项目为独立非官方项目，未修改官方规范的语义，仅在其基础上构建中文实践内容。详细的 attribution 见 NOTICE。

本项目以 Apache-2.0 发布。

如何贡献

欢迎贡献高质量的 Skill、MCP 配置或组合案例。请先阅读 docs/contribution.md，了解示例的质量要求（可运行、可解释、可复用）与工程化约束（可移植、可维护、安全、可观测）。

文档索引