<!-- title: 把Skill发布成可分发插件 -->

# 把本地 Skill 发布成可分发的 Claude Code 插件

> 第 2 轮教程 · Claude Code Skills 进阶实战

## 概述

前面几轮你已经会"从零写一个 SKILL.md"。但一个躺在 `~/.claude/skills/` 里的 Skill 只属于你一个人——同事用不上、换台机器就没了、改了也没人知道。本教程解决这个"最后一公里"问题：**把一个本地 Skill 打包成标准插件（plugin），写一份 `marketplace.json` 目录清单，托管到 Git，让整个团队用一条 `/plugin install` 命令装上并自动更新**。同时引入 2026 年 3 月新增的 **skill-creator eval 基准测试**，在发布前量化验证 Skill 的触发率与输出质量。适合已经写过 Skill、想把它产品化分发给团队或社区的开发者。

## 前置条件

- Claude Code v2.1.143 以上（`displayName` 等字段需要此版本；老版本可省略）
- 已安装 Node.js（用于 `npx` 跑工具）和一个 Git 仓库托管账号（GitHub / GitLab 均可）
- 你手上至少有一个能跑的 `SKILL.md`（没有的话，本教程会顺手造一个）
- 安装官方 skill-creator 插件用于发布前测试：`/plugin install skill-creator@claude-plugins-official`

## 核心概念：Skill、Plugin、Marketplace 三层关系

很多人把这三个词混着用，但它们是**三层不同抽象**，理解清楚才能正确打包：

```mermaid
flowchart TB
    subgraph Layer1["第 1 层：Skill（技能）"]
        S1["SKILL.md\n一段说明 Claude 该怎么做事的指令"]
    end
    subgraph Layer2["第 2 层：Plugin（插件）= 可分发的单元"]
        P1[".claude-plugin/plugin.json"]
        P2["skills/、commands/、agents/、hooks/"]
        P1 --- P2
    end
    subgraph Layer3["第 3 层：Marketplace（市场）= 目录清单"]
        M1[".claude-plugin/marketplace.json"]
        M2["plugins 数组：列出多个插件从哪取"]
        M1 --- M2
    end
    S1 -->|"装进"| P2
    P2 -->|"登记到"| M2
    M2 -->|"托管 Git\n一条命令安装"| User["团队成员的 Claude Code"]
```

一句话：**Skill 是内容，Plugin 是打包格式，Marketplace 是货架**。一个 Marketplace 可以挂多个 Plugin，一个 Plugin 可以装多个 Skill（还能附带 slash command、agent、hook、MCP server）。

## 第 1 步：先造一个要发布的 Skill

我们造一个**真正有用、且本系列没覆盖过的** Skill：`apidoc-gen`——从选中的函数/路由代码自动生成 API 接口文档片段（Markdown 表格 + 示例）。先在本地按标准目录建好骨架：

```bash
mkdir -p my-marketplace/plugins/apidoc-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/apidoc-plugin/skills/apidoc-gen
mkdir -p my-marketplace/.claude-plugin
```

这棵目录树长这样（**结构必须遵守**，Claude Code 靠固定路径识别组件）：

```
my-marketplace/                       ← 仓库根（Marketplace）
├── .claude-plugin/
│   └── marketplace.json              ← 货架清单
└── plugins/
    └── apidoc-plugin/                ← 一个 Plugin
        ├── .claude-plugin/
        │   └── plugin.json           ← 插件清单
        └── skills/
            └── apidoc-gen/
                └── SKILL.md          ← 技能本体
```

写 `SKILL.md`（注意 frontmatter 字段）：

```markdown
---
description: 从选中的函数或路由代码生成 API 接口文档（Markdown 表格 + 请求/响应示例）。当用户要求"生成 API 文档""写接口说明""提取 endpoint"时使用。
disable-model-invocation: false
---

# apidoc-gen

读取用户选中的代码（或最近的改动），识别其中的：
- HTTP 路由路径与方法（GET/POST/PUT/DELETE...）
- 入参（路径参数、查询参数、请求体字段及其类型）
- 返回结构（字段、类型、是否可空）

输出一份 Markdown 接口文档，包含：

| 参数 | 位置 | 类型 | 必填 | 说明 |
|------|------|------|------|------|

随后给出一个最小可用的 `curl` 请求示例和 JSON 响应示例。

规则：
- 类型不确定时标注 `any` 并在说明里写"待确认"，不要编造。
- 若代码里没有明显路由，提示用户并询问要文档化哪个函数。
```

**常见问题**：`description` 写得太宽（如"帮我看代码"）会误触发，写得太窄（如"生成 apidoc"）又触发不了。先随便写，第 2 步用 eval 量化调优。

## 第 2 步：用 skill-creator 跑 Eval，发布前验证质量

这是本系列**第一次引入**的质量闸门。2026 年 3 月 Anthropic 给 skill-creator 加了 eval 能力：给一批测试 prompt，它会告诉你 Skill 在哪些场景会挂。这一步把"我觉得它能跑"变成"数据证明它能跑"。

安装并唤起：

```bash
/plugin install skill-creator@claude-plugins-official
```

然后在对话里直接说：

> 用 skill-creator 给我的 apidoc-gen 技能写 eval：准备 5 个测试 prompt——一个标准 REST 路由、一个带请求体的 POST、一个 Express 风格路由、一个没有路由的纯函数（应触发询问）、一个参数类型模糊的情况（应标注待确认）。每个 prompt 描述"好的输出长什么样"，然后跑 benchmark。

skill-creator 会做三件事：

1. **生成 eval 文件**：一组 `{prompt, 期望行为}` 的测试用例，存在本地。
2. **跑 benchmark**：并行起多个独立 agent（每个干净上下文，避免污染），统计三个关键指标——**通过率（pass rate）、耗时（elapsed time）、token 用量**。
3. **A/B 比对**：可选地拿"有 Skill vs 无 Skill"或"v1 vs v2"做盲评，判断改动是否真的有效。

预期输出（示意）：

```
Eval: apidoc-gen (5 cases)
─────────────────────────────
Case 1 REST GET ......... PASS   1.2s   1.8k tok
Case 2 POST body ........ PASS   1.6s   2.4k tok
Case 3 Express route ..... PASS   1.4s   2.1k tok
Case 4 no-route fn ....... PASS   0.9s   0.7k tok  (正确触发询问)
Case 5 vague type ........ FAIL   1.5s   2.0k tok  (编造了类型)
─────────────────────────────
Pass rate: 4/5 (80%)
```

eval 还能帮你**调 description 的触发精度**：skill-creator 会分析你的 description 对照样本 prompt，建议修改以同时降低"假触发"和"漏触发"。官方在 6 个文档类 Skill 上跑过，5 个触发表现都变好了。

**常见问题**：
- *Case 5 编造类型* → 回到 SKILL.md 把"不确定就标注待确认"的规则加粗、前置。
- *整个 Skill 在新模型上 pass rate 掉了* → 这是能力类 Skill 的正常现象（模型升级可能让 Skill 不再必要），eval 就是为了提前发现。

eval 结果留在你本地，可以接进 CI——每次改 SKILL.md 前先跑一遍，回归一目了然。

## 第 3 步：写 plugin.json——把 Skill 装进插件清单

插件清单放在 `plugins/apidoc-plugin/.claude-plugin/plugin.json`：

```json
{
  "name": "apidoc-plugin",
  "displayName": "API 文档生成器",
  "description": "从代码生成 Markdown API 接口文档与示例",
  "version": "1.0.0",
  "author": { "name": "你的名字", "email": "you@example.com" },
  "homepage": "https://github.com/you/my-marketplace",
  "license": "MIT",
  "keywords": ["docs", "api", "documentation"]
}
```

关键字段说明：

| 字段 | 作用 | 注意点 |
|------|------|--------|
| `name` | 插件唯一标识 | **kebab-case，不能有空格**，用户安装时用它 |
| `version` | 版本号 | **一旦写了这个字段，用户只有在你改它时才收到更新**；不写则每次 git commit 自动算新版本 |
| `displayName` | 界面显示名 | 可含空格大小写，v2.1.143+ 才认；老版本请删掉 |
| `license` | SPDX 标识 | 如 `MIT`、`Apache-2.0`，分发给别人时建议填 |

**踩坑提醒（重要）**：用户安装插件时，Claude Code 会把插件目录**复制到缓存**。这意味着插件**不能用 `../` 引用外部文件**——那些文件不会被复制进来。多个插件要共享文件，请用符号链接（symlink）。

## 第 4 步：写 marketplace.json——给你的插件搭货架

在仓库根的 `.claude-plugin/marketplace.json`：

```json
{
  "name": "my-team-tools",
  "owner": { "name": "平台工具组", "email": "platform@example.com" },
  "description": "团队内部 Claude Code 插件集合",
  "plugins": [
    {
      "name": "apidoc-plugin",
      "source": "./plugins/apidoc-plugin",
      "description": "从代码生成 Markdown API 接口文档与示例",
      "category": "docs",
      "tags": ["api", "documentation", "markdown"]
    }
  ]
}
```

关键字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | **Marketplace 标识，kebab-case**。用户安装时看到它（`/plugin install apidoc-plugin@my-team-tools`）。同名市场只能注册一个，后加的覆盖前一个 |
| `owner` | object | `name` 必填，`email` 可选 |
| `plugins[].source` | string\|object | 插件从哪取。相对路径（`./plugins/xxx`）或 git 对象（见下） |

`source` 支持两种写法。**本地相对路径**（适合仓库内自包含）：

```json
"source": "./plugins/apidoc-plugin"
```

**外部 git 仓库**（适合跨仓库聚合）：

```json
"source": { "source": "github", "repo": "your-org/apidoc-plugin" }
```

**命名禁忌**：以下名字是 Anthropic 官方保留名，第三方市场**不能用**，用了会被拒：`claude-code-marketplace`、`claude-plugins-official`、`claude-plugins-community`、`anthropic-marketplace`、`agent-skills`、`anthropic-agent-skills` 等；连 `official-claude-plugins`、`anthropic-tools-v2` 这种"冒充官方"的名字也会被屏蔽。

## 第 5 步：托管到 Git 并发布

最简单的发布方式就是把这堆文件 push 到一个 Git 仓库。两条路线：

**路线 A：本地市场（团队内快速试用）**——不做任何托管，直接指向本地目录：

```
/plugin marketplace add ./my-marketplace
```

适合你先把流程跑通。

**路线 B：Git 托管（真正的分发）**——把仓库 push 到 GitHub：

```bash
cd my-marketplace
git init && git add -A && git commit -m "feat: apidoc-plugin v1.0.0"
git remote add origin git@github.com:your-org/my-marketplace.git
git push -u origin main
```

团队成员只需一条命令加市场（`owner/repo` 简写会自动解析成对应 git host）：

```
/plugin marketplace add your-org/my-marketplace
```

这就像"添加一个 App Store"：加进来的只是目录，还没装任何插件。用户自己挑要装哪个。

## 第 6 步：安装、测试、命名空间

加好市场后安装插件：

```
/plugin install apidoc-plugin@my-team-tools
```

安装后，**插件里的 Skill 会带命名空间前缀**（避免和别的插件重名）。调用方式：

```
/apidoc-plugin:apidoc-gen
```

测试方法：在编辑器里选中一段路由代码，运行上面的命令，检查是否输出了正确的 Markdown 接口表 + curl 示例。同时按 **Ctrl+O** 看 diagnostics 提示。

更新流程：你改了 SKILL.md 并 bump 了 `plugin.json` 的 `version`（或省略 version 让每次 commit 自动算新版本），push 后用户跑：

```
/plugin marketplace update my-team-tools
```

即可拉到最新版。

**版本策略选择**：

```mermaid
flowchart LR
    A["设置 version 字段"] --> A1["用户只在 version 变化时更新\n适合：稳定发布、语义化版本"]
    B["省略 version"] --> B1["每次 git commit 自动算新版本\n适合：内部快速迭代"]
```

## 第 7 步（可选）：发布到社区市场

如果你想让**全网**用上你的插件，而不只是自己团队，可以提交到 Anthropic 维护的社区市场 `claude-plugins-community`（`github.com/anthropics/claude-plugins-community`）。它和官方市场的区别：

| | 官方市场 `claude-plugins-official` | 社区市场 `claude-plugins-community` |
|---|---|---|
| 来源 | Anthropic 精选 | 第三方，通过自动校验+安全筛查 |
| 可见性 | 启动 Claude Code 自动可用 | 需手动 `/plugin marketplace add` |
| 版本锁定 | — | 每个插件**固定到某个 commit SHA** |
| 提交方式 | Anthropic 自行挑选 | 通过应用内表单提交 |

提交路径：在 Claude Code 里用 `/plugin` 的提交表单把你的插件推到社区市场。注意提交进去的是**社区市场**，不是官方市场——官方市场的收录完全由 Anthropic 决定。

## 实战案例：完整的 apidoc-plugin 仓库

把前面所有步骤拼起来，最终可发布的仓库长这样（你只需照着建文件）：

```bash
# 1. 目录结构
my-marketplace/
├── .claude-plugin/marketplace.json      # 第 4 步
└── plugins/apidoc-plugin/
    ├── .claude-plugin/plugin.json        # 第 3 步
    └── skills/apidoc-gen/SKILL.md        # 第 1 步

# 2. 发布前跑 eval（第 2 步）
/plugin install skill-creator@claude-plugins-official
# → 对话里要求写 5 条 eval 并 benchmark，确认 pass rate ≥ 80%

# 3. 本地自测（路线 A）
/plugin marketplace add ./my-marketplace
/plugin install apidoc-plugin@my-team-tools
/apidoc-plugin:apidoc-gen        # 选中代码后调用，验证输出

# 4. 正式发布（路线 B）
git init && git add -A
git commit -m "feat: apidoc-plugin v1.0.0"
git push origin main

# 5. 团队成员消费
/plugin marketplace add your-org/my-marketplace
/plugin install apidoc-plugin@my-team-tools
```

端到端工作流全景：

```mermaid
flowchart TD
    A["写 SKILL.md"] --> B["skill-creator 写 eval"]
    B --> C["跑 benchmark\n看 pass rate/token"]
    C -->|"FAIL"| A
    C -->|"PASS ≥ 阈值"| D["写 plugin.json"]
    D --> E["写 marketplace.json"]
    E --> F{"托管方式"}
    F -->|"本地试用"| G["/plugin marketplace add ./dir"]
    F -->|"Git 发布"| H["push 到 GitHub"]
    H --> I["/plugin marketplace add org/repo"]
    G --> J["/plugin install xxx@market"]
    I --> J
    J --> K["/plugin-name:skill 调用"]
    K --> L["更新：bump version\n用户 marketplace update"]
    H --> M["（可选）提交社区市场\nclaude-plugins-community"]
```

## 常见问题与排错

**Q：`/plugin install` 报"plugin not found in any marketplace"？**
市场没注册或过时。先 `/plugin marketplace update <market-name>` 刷新，或 `/plugin marketplace add <org/repo>` 重新添加，再重试。

**Q：装上后 Skill 不触发？**
大概率是 `description` 精度问题。用 skill-creator 的"触发调优"对照样本 prompt 检查，降低假阳/假阴。

**Q：插件里引用了 `../shared/utils` 的文件，安装后失效？**
插件安装时会复制到缓存，跨目录引用失效。改用 symlink 共享，或把共享文件直接放进插件目录。

**Q：改了 SKILL.md，团队那边没更新？**
检查是否 `plugin.json` 设了 `version`——设了就必须 bump 才推更新。或干脆省略 version，靠 commit SHA 自动迭代。

**Q：升级到新模型后 Skill 表现变差？**
对"能力提升类"Skill 是正常的。重跑 eval：若基座模型不开 Skill 也能 pass，说明这个 Skill 已被模型默认能力吸收，可以退役。

**Q：`displayName` 不生效？**
需要 Claude Code v2.1.143+。老版本忽略它，删掉该字段即可（不影响 `name`）。

## 进阶：一个 Plugin 装多个组件

Plugin 不止能装 Skill，还能同时打包 slash command、subagent、hook、MCP server——这才是 plugin 相对裸 Skill 的真正价值。结构扩展：

```
plugins/apidoc-plugin/
├── .claude-plugin/plugin.json
├── skills/apidoc-gen/SKILL.md
├── commands/check-api.md          ← /apidoc-plugin:check-api
├── agents/spec-writer.md          ← 子代理
└── hooks/hooks.json               ← 钩子（如保存即检查）
```

一个 plugin 就能把"文档生成 + 命令 + 代理 + 钩子"作为一个整体分发、整体版本管理，比散落的 Skill 整洁得多。

## 延伸阅读

- 官方：[Create and distribute a plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces) — 完整 marketplace.json schema 与保留名清单
- 官方：[Discover and install prebuilt plugins](https://code.claude.com/docs/en/discover-plugins) — 官方/社区市场、LSP 插件清单
- 官方：[skill-creator 插件页](https://claude.com/plugins/skill-creator) — eval/benchmark/comparator 能力
- 博客：[Improving skill-creator: Test, measure, and refine Agent Skills](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills)（2026-03-03）— eval 设计动机与多 agent 并行评测
- 社区：[anthropics/claude-plugins-community](https://github.com/anthropics/claude-plugins-community) — 第三方插件提交入口

## 训练营适用性评估

- **适合训练营类型**：Claude Code 进阶/工程化训练营、企业内部 AI 工具链培训、"团队效能"主题工作坊。不适合零基础营（需要先掌握 SKILL.md 基础，属第 1 轮内容）。
- **前置依赖**：学员需已完成"从零创建 Skill"的基础课。
- **预计教学时长**：3–4 小时（含动手）。其中 Skill 编写 30 分钟、eval 跑通 60 分钟、打包与 marketplace 各 45 分钟、发布排错 45 分钟。
- **可考核产出**：每位学员产出一个含 `marketplace.json` + `plugin.json` + eval 报告、push 到自己 GitHub、且他人能 `/plugin install` 成功的完整插件仓库。
- **难度定位**：中阶偏上，重点不在写 Skill，而在"工程化打包 + 质量验证 + 分发"这条流水线。

## 参考来源

1. [Create and distribute a plugin marketplace — Claude Code Docs](https://code.claude.com/docs/en/plugin-marketplaces) — 官方插件市场创建与分发指南，含 marketplace.json / plugin.json 完整 schema 与保留名清单
2. [Discover and install prebuilt plugins — Claude Code Docs](https://code.claude.com/docs/en/discover-plugins) — 官方/社区市场机制、LSP 与外部集成插件目录
3. [Improving skill-creator: Test, measure, and refine Agent Skills — Claude Blog (2026-03-03)](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills) — skill-creator 的 eval、benchmark、A/B 比对与 description 触发调优官方公告
4. [Skill Creator — Claude Plugins](https://claude.com/plugins/skill-creator) — 官方 skill-creator 插件页，能力与安装方式
5. [anthropics/claude-plugins-community — GitHub](https://github.com/anthropics/claude-plugins-community) — 第三方社区市场仓库与提交流程

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)