第 2 轮教程 · Claude Code Skills 进阶实战
前面几轮你已经会"从零写一个 SKILL.md"。但一个躺在 ~/.claude/skills/ 里的 Skill 只属于你一个人——同事用不上、换台机器就没了、改了也没人知道。本教程解决这个"最后一公里"问题：把一个本地 Skill 打包成标准插件（plugin），写一份 marketplace.json 目录清单，托管到 Git，让整个团队用一条 /plugin install 命令装上并自动更新。同时引入 2026 年 3 月新增的 skill-creator eval 基准测试，在发布前量化验证 Skill 的触发率与输出质量。适合已经写过 Skill、想把它产品化分发给团队或社区的开发者。
displayName 等字段需要此版本；老版本可省略）npx 跑工具）和一个 Git 仓库托管账号（GitHub / GitLab 均可）SKILL.md（没有的话，本教程会顺手造一个）/plugin install skill-creator@claude-plugins-official很多人把这三个词混着用，但它们是三层不同抽象，理解清楚才能正确打包：
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）。
我们造一个真正有用、且本系列没覆盖过的 Skill：apidoc-gen——从选中的函数/路由代码自动生成 API 接口文档片段（Markdown 表格 + 示例）。先在本地按标准目录建好骨架：
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 字段）：
---
description: 从选中的函数或路由代码生成 API 接口文档（Markdown 表格 + 请求/响应示例）。当用户要求"生成 API 文档""写接口说明""提取 endpoint"时使用。
disable-model-invocation: false
---
# apidoc-gen
读取用户选中的代码（或最近的改动），识别其中的：
- HTTP 路由路径与方法（GET/POST/PUT/DELETE...）
- 入参（路径参数、查询参数、请求体字段及其类型）
- 返回结构（字段、类型、是否可空）
输出一份 Markdown 接口文档，包含：
| 参数 | 位置 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
随后给出一个最小可用的 `curl` 请求示例和 JSON 响应示例。
规则：
- 类型不确定时标注 `any` 并在说明里写"待确认"，不要编造。
- 若代码里没有明显路由，提示用户并询问要文档化哪个函数。
常见问题：description 写得太宽（如"帮我看代码"）会误触发，写得太窄（如"生成 apidoc"）又触发不了。先随便写，第 2 步用 eval 量化调优。
这是本系列第一次引入的质量闸门。2026 年 3 月 Anthropic 给 skill-creator 加了 eval 能力：给一批测试 prompt，它会告诉你 Skill 在哪些场景会挂。这一步把"我觉得它能跑"变成"数据证明它能跑"。
安装并唤起：
/plugin install skill-creator@claude-plugins-official
然后在对话里直接说：
用 skill-creator 给我的 apidoc-gen 技能写 eval：准备 5 个测试 prompt——一个标准 REST 路由、一个带请求体的 POST、一个 Express 风格路由、一个没有路由的纯函数（应触发询问）、一个参数类型模糊的情况（应标注待确认）。每个 prompt 描述"好的输出长什么样"，然后跑 benchmark。
skill-creator 会做三件事：
{prompt, 期望行为} 的测试用例，存在本地。预期输出（示意）：
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 前先跑一遍，回归一目了然。
插件清单放在 plugins/apidoc-plugin/.claude-plugin/plugin.json：
{
"name": "apidoc-plugin",
"displayName": "API 文档生成器",
"description": "从代码生成 Markdown API 接口文档与示例",
"version": "1.0.0",
"author": { "name": "你的名字", "email": "[email protected]" },
"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）。
在仓库根的 .claude-plugin/marketplace.json：
{
"name": "my-team-tools",
"owner": { "name": "平台工具组", "email": "[email protected]" },
"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 支持两种写法。本地相对路径（适合仓库内自包含）：
"source": "./plugins/apidoc-plugin"
外部 git 仓库（适合跨仓库聚合）：
"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 这种"冒充官方"的名字也会被屏蔽。
最简单的发布方式就是把这堆文件 push 到一个 Git 仓库。两条路线：
路线 A：本地市场（团队内快速试用）——不做任何托管，直接指向本地目录：
/plugin marketplace add ./my-marketplace
适合你先把流程跑通。
路线 B：Git 托管（真正的分发）——把仓库 push 到 GitHub：
cd my-marketplace
git init && git add -A && git commit -m "feat: apidoc-plugin v1.0.0"
git remote add origin [email protected]:your-org/my-marketplace.git
git push -u origin main
团队成员只需一条命令加市场（owner/repo 简写会自动解析成对应 git host）：
/plugin marketplace add your-org/my-marketplace
这就像"添加一个 App Store"：加进来的只是目录，还没装任何插件。用户自己挑要装哪个。
加好市场后安装插件：
/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
即可拉到最新版。
版本策略选择：
flowchart LR
A["设置 version 字段"] --> A1["用户只在 version 变化时更新\n适合：稳定发布、语义化版本"]
B["省略 version"] --> B1["每次 git commit 自动算新版本\n适合：内部快速迭代"]
如果你想让全网用上你的插件，而不只是自己团队，可以提交到 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 决定。
把前面所有步骤拼起来，最终可发布的仓库长这样（你只需照着建文件）：
# 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
端到端工作流全景：
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 不止能装 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 整洁得多。
marketplace.json + plugin.json + eval 报告、push 到自己 GitHub、且他人能 /plugin install 成功的完整插件仓库。[!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 等场景全覆盖。