Skill: binbin1213/skill-reviewer-2 (version 0.1.0)

--- name: skill-reviewer description: 审核/审查 Skill 代码质量的专业工具。当用户说"检查 skill"、"审核 skill"、"review {名称} skill"、"skill 写得怎么样"、"帮我看看这个 skill 有什么问题"时使用。依据 Anthropic 官方指南进行结构验证、YAML 前置信息检查、描述质量评估、指令完整性审查，并输出详细的问题报告和改进建议。 --- # Skill Reviewer > **说明**：这是一个Skill审核工具，用于审核其他技能的质量。文档中包含的"错误示例"（如无效 YAML、错误命名等）仅用于教学演示，展示不应该怎么写。不存在任何恶意或混淆代码。 依据 Anthropic 官方 Skills 开发指南，对技能进行全面审核。提供结构化审核框架、评分系统、缺陷检查清单和改进建议。 ## 核心职责 1. **结构验证** - 检查文件夹结构、文件命名规范 > 示例：`ls skills/my-skill/` 检查 `SKILL.md` 是否存在 2. **YAML 审核** - 验证前置信息格式和必填字段 > 示例：`head -20 SKILL.md` 检查 name/description 3. **描述评估** - 检查触发条件是否清晰 > 示例：description 应包含"当用户...时"触发条件 4. **组织评分** - 评估技能是否按任务组织、常见操作优先 > 示例："## 编码和解码" ✅ vs "## 理论" ❌ 5. **指令审查** - 评估主体指令的质量和完整性 > 示例：是否有工作流程、示例、错误处理 6. **示例质量** - 评估示例密度和可执行性 > 示例：每 5-30 行 1 个代码块为最佳密度 7. **Tips 评分** - 评估技巧部分的质量和价值 > 示例：5-10 条非显而易见的实用技巧 8. **最佳实践** - 对照官方指南检查合规性 > 示例：检查是否按任务组织而非抽象概念 ## 工作流程 ### 第 1 步：接收审核请求 当用户请求审核 skill 时： 1. 确认 skill 文件夹路径或读取 SKILL.md 内容 2. 判断审核严格程度： **严格模式（必须读取完整版官方指南）：** 当用户表达以下意图时，必须先读取 `references/anthropic-skills-development-guide.md` 完整版指南： - 明确要求"严格检查"、"仔细审核"、"全面审查" - 提到"高质量要求"、"生产级别"、"发布前检查" - 表达"不想有任何遗漏"、"按最高标准" - 用于团队/组织/公司项目 - 准备公开发布或分享给他人 **常规模式：** - 优先读取 `references/checklist.md`（快速检查清单） - 遇到疑问或边缘案例时读取完整版官方指南 --- ### 第 2 步：结构检查 **文件夹结构验证：** ```text [ ] 技能文件夹使用 kebab-case 命名（如 my-skill） [ ] SKILL.md 存在且命名精确（区分大小写） [ ] 无 README.md 在技能文件夹内 [ ] 可选文件夹（如存在）命名规范 ``` **可选文件夹命名规范（如存在）：** - [ ] `scripts/` - 全小写复数，无空格/下划线 - [ ] `references/` - 全小写复数，无空格/下划线 - [ ] `assets/` - 全小写复数，无空格/下划线 **❌ 错误示例：** `Scripts`、`script`、`scripts_backup`、`References`、`refs`、`Assets`、`asset_files` **示例：检查文件夹结构** ```bash # 查看技能文件夹结构 ls -la skills/china-holidays/ ``` **预期输出：** ```text skills/china-holidays/ ├── SKILL.md # ✅ 正确：精确命名 └── references/ # ✅ 正确：全小写复数 └── calendar-guide.md ``` **评分：__/4** --- ### 第 3 步：YAML 前置信息检查 **必填字段验证：** ```text [ ] name 字段存在，kebab-case，无空格大写 [ ] description 字段存在，非空 [ ] YAML 分隔符完整（--- 开头和结尾） [ ] 无 XML 标签（< >） [ ] name 不以 claude/anthropic 开头 ``` **示例：验证 YAML 前置信息** ```bash # 读取前 20 行检查 YAML head -20 skills/china-holidays/SKILL.md ``` **预期输出（正确示例）：** ```yaml --- name: china-holidays description: 获取中国国家法定节假日安排。当用户询问"放假安排"、"节假日"时使用。 --- ``` **错误示例（应该拒绝）：** ```yaml name: ChinaHolidays # ❌ 大写，应该 kebab-case name: claude-scheduler # ❌ 以 claude 开头 description: "" # ❌ 空描述 <skill> # ❌ 包含 XML 标签 ``` **Description 质量评分（满分 8 分）：** ```text [2] 开头说明做什么（主动动词） 好："分析 Figma 设计文件并生成开发者交接文档" 差："这是关于 Figma 的技能" [2] 包含触发条件（"当用户...时"） 好："当用户上传 .fig 文件或询问设计规格时使用" 差：无触发条件 [2] 具体范围（提及具体工具、操作或场景） 好："Figma 设计文件、.fig、组件文档、设计交接" 差："帮助处理项目" [2] 合理长度（50-200 字符，不超过 1024） 太短：无搜索价值 太长：被截断 ``` **评分：__/8** --- ### 第 4 步：组织评分 **按任务/场景组织（而非按抽象概念）：** ```text [2] 按任务/操作组织章节 好："## 编码和解码" → "## 检查字符" → "## 转换格式" 差："## 理论" → "## 类型" → "## 高级" [2] 常见操作优先 好：基础用法 → 变体 → 高级 → 边界情况 差：配置说明 → 理论背景 → 最后才是基础用法 [1] 章节自包含（可独立使用） [1] 深度一致（不混用 h2 与 h4 随机跳转） ``` **评分：__/6** --- ### 第 5 步：主体指令检查 **必须包含：** ```text [ ] 清晰的工作流程或步骤说明 [ ] 至少一个使用示例 [ ] 错误处理或故障排查指南 ``` **推荐包含（不扣分）：** ```text [ ] 预期输出说明 [ ] 多个场景示例 [ ] 参考文档链接 [ ] "使用场景" 或 "When to Use" 部分 ``` **评分：__/6** --- ### 第 6 步：示例质量评估 **示例密度计算：** ```text 总行数：___ 代码块数量：___ 密度：每 ___ 行 1 个代码块 参考目标：每 5-30 行 1 个代码块 < 5 行/块：可能过于碎片化（短命令集或多命令速查除外） > 40 行/块：需要更多示例 ``` **示例密度评分：** ```text [3] 密度在 5-30 行/块范围内 [2] 密度略低（30-40 行/块）或略高（3-5 行/块） [0] 密度严重不足（>40 行/块）或过高（<3 行/块） ``` **每个示例质量评分（0-3 分）：** ```text [ ] 语言标签正确（```bash, ```python 等） [ ] 语法正确，命令可执行 [ ] 展示了预期输出或结果说明 [ ] 使用真实值（非 foo/bar/baz） [ ] 无占位符（TODO, FIXME, xxx） [ ] 自包含或有设置说明 0 分：broken 或有误导性 1 分：可用但简陋（无输出/上下文） 2 分：良好（正确，有输出或说明） 3 分：优秀（可直接复制，真实，覆盖边界） ``` **示例质量得分 = 所有示例平均分 × 密度分 / 3 = __/9** --- ### 第 7 步：可执行性评估 核心问题：Agent 能否按照这些指令产生正确结果？ ```text [3] 使用祈使句（"运行 X"、"创建 Y"） 非："可以考虑..."或"建议..."或"You might..." [3] 步骤顺序合理（前置条件在行动之前） [2] 错误处理（说明失败时怎么做） [2] 输出/结果描述（如何验证成功） ``` **评分：__/10** --- ### 第 8 步：渐进式披露检查 ```text [ ] SKILL.md 控制在 500 行以内 500-600 行：给出提醒，不扣分 超过 600 行：扣分 [ ] 详细文档是否在 `references/` 中 [ ] 大文件（>300 行）有目录或结构说明 ``` **评分：__/3** --- ### 第 9 步：Tips 评分 **技巧部分质量评估：** ```text [2] 5-10 条技巧 少于 5 条：覆盖不足 多于 10 条：可能不够精炼 [2] 技巧非显而易见 好："Makefile 头号陷阱：缩进必须用 Tab，不能用空格" 差："确保测试你的代码" [2] 技巧具体可执行 好："使用 flock 防止 cron 任务重叠执行" 差："小心并发执行" [1] 技巧不矛盾主体内容 [1] 技巧覆盖特定主题的陷阱/踩坑点 ``` **评分：__/8** --- ### （可选）Metadata 参考 > 仅当 skill 包含 metadata 字段时检查，仅供参考，不计分 ```text [ ] emoji 与技能主题相关 [ ] requires.anyBins 列出技能实际使用的工具（非 generic 如 bash） [ ] os 数组准确（不包含不支持的平台） [ ] JSON 格式有效 ``` --- ## 评分总结 ```text SKILL 审核评分卡 ═══════════════════════════════════════ 技能名称：{name} 审核者：{agent/human} 日期：{date} 审核模式：{严格/常规} 类别 得分 满分 ───────────────────────────────────── 结构检查 __ 4 Description 质量 __ 8 组织评分 __ 6 主体指令 __ 6 示例质量 __ 9 可执行性 __ 10 渐进式披露 __ 3 Tips 评分 __ 8 ───────────────────────────────────── 总分 __ 54 转换为百分制：总分 × 1.85 = ___/100 评级： 85+ 优秀 — 可直接发布 70-84 良好 — 需要小改进 50-69 一般 — 需要明显改进 < 50 较差 — 需要重大修改 结论：{PUBLISH / REVISE / REWORK} ``` --- ## 常见缺陷 ### 严重缺陷（阻止发布） ```text 缺陷：YAML 前置信息无效 检测：YAML 解析错误、缺少必填字段 修复：验证 YAML 格式，确保 name/description 都存在 缺陷：代码示例损坏 检测：语法错误、未定义变量、错误参数 修复：在干净环境中测试每个命令 缺陷：工具要求不匹配（如存在 metadata） 检测：requires 列出内容未在内容中使用 修复：grep 内容提取命令名，更新 requires 匹配 缺陷：误导性描述 检测：描述承诺的内容实际未覆盖 修复：使描述与实际内容一致，或补充缺失内容 ``` ### 主要缺陷（发布前应该修复） ```text 缺陷：缺少"使用场景"部分 影响：Agent 不知道何时激活技能 修复：添加 4-8 条触发场景说明 缺陷：大段文字无示例 检测：任何超过 10 行无代码块的章节 修复：为每个概念添加具体示例 缺陷：示例缺少语言标签 检测：\`\`\` 后无语言标识符 修复：为每个代码块添加 bash/python/javascript/yaml 等 缺陷：缺少 Tips/技巧部分 影响：缺少使技能有价值的经验总结 修复：添加 5-10 条非显而易见的实用技巧 缺陷：按抽象概念组织 检测：章节名为"理论"、"概述"、"背景"、"介绍" 修复：按任务/操作重组：用户要做什么 ``` ### 次要缺陷（建议修复） ```text 缺陷：占位符值 检测：foo, bar, baz, example.com, TODO, FIXME 修复：替换为真实值 缺陷：格式不一致 检测：混合标题级别、代码块样式不一致 修复：统一标题层次和格式 缺陷：缺少交叉引用 检测：提到其他技能覆盖的工具/概念但未引用 修复：添加"参见 X 技能了解更多"注释 缺陷：过时的命令 检测：旧语法或已弃用工具 修复：更新为当前工具版本和语法 ``` --- ## 快速审核模板 当不需要完整评分时的快速审核： ```markdown ## 快速审核：{skill-name} **结构**：[通过/问题：...] **Description**：[强/弱：原因] **示例**：[X 个代码块，共 Y 行 — 密度 正常/低/高] **可执行性**：[Agent 可以/不可以 遵循这些指令，因为...] **首要缺陷**：[最应该修复的单一问题] **评分**：__/100 **结论**：[PUBLISH / REVISE / REWORK] ``` --- ## 审核工作流 ### 发布前自查 ```bash # 1. 验证 YAML 前置信息 head -20 skills/my-skill/SKILL.md # 目视确认 YAML 有效 # 2. 统计代码块数量 grep -c '```' skills/my-skill/SKILL.md # 总行数除以这个数得密度 # 3. 检查占位符 grep -n -i 'todo\|fixme\|xxx\|foo\|bar\|baz' skills/my-skill/SKILL.md # 4. 检查缺失语言标签 grep -n '^```$' skills/my-skill/SKILL.md # 每个代码块都应该有语言标签 # 5. 验证工具要求匹配内容（如存在 metadata） # 提取 requires，然后 grep 内容检查每个工具 # 6. 测试命令（抽样 3-5 个） # 在干净 shell 中运行验证 # 7. 运行评分卡 # 目标：良好 35+，优秀 45+ ``` **示例：完整审核报告输出** ```markdown ## 审核报告：china-holidays **结构**：✅ 通过 - kebab-case 命名，SKILL.md 存在 **Description**：✅ 强 - 包含触发条件和具体场景 **示例**：18 个代码块，524 行 — 密度 正常 (29 行/块) **可执行性**：✅ 可以遵循 - 9 步清晰工作流程 **评分总结**： ───────────────────────────────────── 结构检查 4 4 Description 质量 8 8 组织评分 6 6 主体指令 6 6 示例质量 7 9 可执行性 10 10 渐进式披露 3 3 Tips 评分 8 8 ───────────────────────────────────── 总分 52 54 百分制：96/100 **结论**：PUBLISH - 可直接发布 ``` ### 审核他人技能 ```bash # 安装技能（如适用） npx molthub@latest install skill-name # 阅读内容 cat skills/skill-name/SKILL.md # 运行快速审核模板 # 如分数 < 25，考虑卸载并寻找替代 ``` --- ## 参考文件 按使用场景分层： | 文件 | 用途 | 何时读取 | |------|------|----------| | `references/checklist.md` | 快速检查清单 | 常规审核流程 | | `references/official-guide-summary.md` | 精简指南 | 快速查阅常用规范 | | `references/anthropic-skills-development-guide.md` | 完整版官方指南 | **严格模式下必须读取**；常规模式下遇到疑问时查阅 | **严格模式触发条件**（满足任一即触发）： - 用户明确要求"严格检查"、"全面审查"、"仔细审核" - 提到"高质量"、"生产级别"、"发布前" - 表达"不想有遗漏"、"按最高标准" - 用于团队/组织/公司项目 - 准备公开发布或分享 **审核时先判断模式**：严格模式必须先读取完整版指南再进行审核；常规模式按需查阅。 --- ## 示例 ### 示例 1：完整审核 **用户说：** "帮我审核一下这个 skill，路径在 ./skills/china-holidays" **操作：** 1. 读取 `./skills/china-holidays/SKILL.md` 2. 判断审核模式（默认常规） 3. 按照评分卡逐项检查 4. 生成审核报告 5. 解读结果并提供改进建议 **结果：** 输出完整审核报告，包含问题列表、修改建议和最终评分 ### 示例 2：严格模式审核 **用户说：** "这个 skill 准备发布到团队内部使用，需要严格检查，不能有任何问题" **操作：** 1. 触发严格模式 2. **必须**先读取 `anthropic-skills-development-guide.md` 3. 对照官方指南逐项严格检查 4. 输出详细报告，确保无遗漏 ### 示例 3：快速检查 description **用户说：** "这个 skill 的 description 写得怎么样？" + 附上内容 **操作：** 1. 聚焦 description 字段分析 2. 使用 8 分评分标准 3. 提供改进建议 **结果：** 指出问题并提供修改建议 --- ## 技巧 - **Description 最重要** — 它占实际影响力的 40% 以上。完美的 skill 配上糟糕的 description 也不会被找到。 - **先数代码块** — 少于 8 个代码块的 skill 几乎总是过于抽象而无用。 - **在干净环境测试 3-5 个命令** — 如超过 1 个失败，说明 skill 发布前未测试。 - **按任务组织 vs 按概念组织** — 这是最关键的结构质量差异。好技能回答"如何做 X"，坏技能解释"X 是什么"。 - **有好 Tips 但示例弱的 skill，比有好示例但没 Tips 的更有价值** — Tips 编码了示例无法传达的专业知识。 - **检查 requires 与实际使用是否匹配** — 常见缺陷是列出 bash（所有都有）而不是实际工具如 docker、curl、jq。 - **过短的 skill（<150 行）通常不值得发布** — 它们提供的价值不如快速网络搜索。如果 skill 太短，可能是更大 skill 的一个章节。 - **最佳标准：你自己会收藏使用吗** — 如果你自己不会用，就不要发布。

path: references/anthropic-skills-development-guide.md
content: # 万字译文：Anthropic官方发布的Claude Skills构建指南完整版！

> Anthropic刚刚官方发布了33页的Claude Skills构建指南，下面是全文中文译版，pls enjoy ~

---

## 目录

- 简介
- 第一章 基础知识
- 第二章 规划与设计
- 第三章 测试与迭代
- 第四章 发布与分享
- 第五章 模式与故障排查
- 第六章 资源与参考

---

## 简介

技能（Skill）其实就是一套指令**打包成一个简单的文件夹**用来教 Claude 怎么处理特定任务或工作流程。这是你自定义 Claude 最有力的方式之一。

你有没有遇到过这种情况：每次跟 Claude 对话，都要重新解释你的偏好、流程和专业背景？有了技能，你只需要教一次，以后每次都能直接用上。

什么时候用技能最合适？就是当你有 **可以重复执行的工作流程** 时，比如：

- 根据设计稿生成前端界面
- 用固定的方法论做研究调查
- 按照团队风格指南写文档
- 协调多个步骤的复杂流程

技能跟 Claude 的内置功能（比如执行代码、创建文档）搭配起来效果很好。如果你在做 MCP 集成，技能还能帮你把原始的工具访问能力，变成可靠、顺畅的工作流程。

**读完这份指南，你会学到：**

- 技能的技术要求和最佳实践
- 独立技能和 MCP 增强型工作流的设计模式
- 我们观察到的那些真正有效的做法
- 怎么测试、迭代、发布你的技能

**这份指南适合谁读？**

- 想让 Claude 按固定流程工作的开发者
- 想让 Claude 遵循自己习惯的高级用户
- 想在团队/组织内统一 Claude 使用方式的管理者

**两条阅读路径：**
只做独立技能？重点看"基础知识"和"规划与设计"部分。
想在 MCP 上叠加技能？"技能 + MCP"和第五章的设计模式更适合你。

两条路径用的是同样的技术规范，按自己的需求选就好。

> **预计投入：** 读完这份指南后，配合 skill-creator 工具，通常 15-30 分钟就能做出你第一个能用的技能。

---

## 第一章：基础知识

### 技能到底是什么？

技能就是一个文件夹，里面放着：

| 文件/文件夹   | 是否必须 | 作用                                 |
| ------------- | -------- | ------------------------------------ |
| `SKILL.md`    | ✅ 必须   | 带 YAML 前置信息的 Markdown 格式指令 |
| `scripts/`    | 可选     | 可执行代码（Python、Bash 等）        |
| `references/` | 可选     | 按需加载的参考文档                   |
| `assets/`     | 可选     | 输出用的模板、字体、图标等           |

### 三个核心设计理念

**1. 渐进式披露（Progressive Disclosure）**

技能用三层结构来组织内容：

- **第一层（YAML 前置信息）**：每次都会加载到 Claude 的系统提示里。内容要精简——让 Claude 知道"这个技能是做什么的、什么时候该用它"就够了，不需要把所有东西都塞进来。
- **第二层（SKILL.md 正文）**：当 Claude 觉得当前任务跟这个技能有关，才会加载完整指令。
- **第三层（链接文件）**：放在技能文件夹里的其他文件，Claude 可以按需查阅。

这种分层设计的好处：既省 token，又能保留足够的专业深度。

**2. 可组合性（Composability）**

Claude 可以同时加载多个技能。你的技能要能跟其他技能和平共处，别假设自己是唯一被启用的那个。

**3. 可移植性（Portability）**

在 Claude.ai、Claude Code 和 API 里，技能的工作方式完全一样。写一次，到处能用——前提是运行环境支持技能所需的依赖。

---

### 面向 MCP 开发者：用技能增强 MCP

> 💡 只做独立技能、不涉及 MCP？可以直接跳到第二章，随时回来看这节。

如果你已经有了运行中的 MCP 服务器，最难的部分其实已经搞定了。技能就是在上面加一层"知识层"——把你已经知道的工作流程和最佳实践固化下来，让 Claude 能够一致地应用它们。

**这两者怎么配合？**

| MCP（连接层）                                        | 技能（知识层）                   |
| ---------------------------------------------------- | -------------------------------- |
| 把 Claude 连接到你的服务（Notion、Asana、Linear 等） | 教 Claude 怎么有效地使用这些服务 |
| 提供实时数据访问和工具调用能力                       | 固化工作流程和最佳实践           |
| Claude 能做什么                                      | Claude 应该怎么做                |

**没有技能时，用户可能遇到的问题：**

- 连上了 MCP，但不知道下一步该咋办
- 不断发来"怎么用你的集成做 X"的支持提问
- 每次对话从头开始，结果每次都不一样
- 用户会把问题归咎于你的 MCP 连接器，但根本原因其实是缺少工作流程指引

**有了技能之后：**

- 预置的工作流程在需要时自动激活
- 工具调用稳定可靠
- 最佳实践内嵌在每次交互里
- 新用户的学习成本大幅降低

---

## 第二章：规划与设计

### 第一步：从用例出发

在写任何代码之前，先想清楚你的技能要解决的 **2-3 个具体场景**。

一个好的用例定义长这样：

```
用例：项目冲刺规划

触发条件：用户说"帮我规划这个冲刺"或"创建冲刺任务"

步骤：
  1. 通过 MCP 获取 Linear 的当前项目状态
  2. 分析团队速度和容量
  3. 建议任务优先级
  4. 在 Linear 里创建带标签和估算的任务

结果：冲刺计划规划完毕，任务全部创建好
```

问自己这几个问题：

- 用户想达成什么目标？
- 这需要哪些多步骤的工作流程？
- 需要哪些工具（Claude 内置的，还是 MCP 的）？
- 需要嵌入哪些领域知识或最佳实践？

### 三类常见用例

Anthropic 观察到三种最常见的技能使用场景：

**第 1 类：文档和素材创建**

适合场景：创建一致的高质量输出，比如文档、演示文稿、应用、设计、代码等。

真实案例：`frontend-design` 技能（另见 docx、pptx、xlsx 相关技能）

```
"创建有辨识度的、生产级别的前端界面，注重设计质量。
在构建 Web 组件、页面、作品、海报或应用时使用。"
```

关键做法：

- 嵌入风格指南和品牌规范
- 用模板结构保证输出一致
- 最终确认前做质量清单检查
- 不需要外部工具——用 Claude 的内置能力就够

**第 2 类：工作流程自动化**

适合场景：多步骤流程，需要一致的执行方式，可能跨多个 MCP 服务器协调。

真实案例：`skill-creator` 技能

```
"创建新技能的交互式向导。
引导用户完成用例定义、前置信息生成、指令撰写和验证。"
```

关键做法：

- 带验证节点的分步工作流
- 常见结构的模板
- 内置审查和改进建议
- 迭代优化循环

**第 3 类：MCP 增强**

适合场景：为 MCP 服务器的工具访问能力加上工作流程引导。

真实案例：来自 Sentry 的 `sentry-code-review` 技能

```
"利用 Sentry 错误监控数据，通过其 MCP 服务器
自动分析和修复 GitHub Pull Requests 中发现的 bug。"
```

关键做法：

- 按顺序协调多个 MCP 调用
- 嵌入领域专业知识
- 提供用户本来需要手动指定的上下文
- 处理常见 MCP 问题

### 第二步：定义成功标准

怎么知道你的技能跑通了？

先说清楚：下面这些是参考目标，不是死板的门槛——测试时还是需要一定的感性判断。Anthropic 正在开发更完善的量化评估工具。

**量化指标：**

- 技能在 90% 的相关查询中触发
- 怎么测：跑 10-20 个应该触发技能的测试问题，记录自动加载的次数
- 工作流程在 X 次工具调用内完成
- 怎么测：有无技能各跑一次相同任务，对比工具调用次数和 token 消耗
- 每个工作流程 0 次 API 调用失败
- 怎么测：测试期间监控 MCP 服务器日志，追踪重试率和错误码

**定性指标：**

- 用户不需要提示 Claude 下一步该做什么
- 工作流程无需用户纠正就能跑完
- 跨会话结果保持一致

---

### 技术要求

#### 文件夹结构

```
your-skill-name/
├── SKILL.md              # 必须——主技能文件
├── scripts/              # 可选——可执行代码
│   ├── process_data.py
│   └── validate.sh
├── references/           # 可选——参考文档
│   ├── api-guide.md
│   └── examples/
└── assets/               # 可选——模板等资源
    └── report-template.md
```

#### 几条必须遵守的规则

**SKILL.md 命名：**

- 必须精确写成 `SKILL.md`（区分大小写）
- 任何变体都不行：`SKILL.MD`、`skill.md` 都不能用

**技能文件夹命名：**

- ✅ 用 kebab-case（短横线连接小写）：`notion-project-setup`
- ❌ 不能有空格：`Notion Project Setup`
- ❌ 不能用下划线：`notion_project_setup`
- ❌ 不能有大写：`NotionProjectSetup`

**不要放 README.md：**

- 技能文件夹内别放 README.md
- 所有文档放在 SKILL.md 或 references/ 里
- 注意：通过 GitHub 发布时，仓库根目录仍然需要 README 供人类查阅——这和技能文件夹是两回事

---

### YAML 前置信息：最关键的部分

YAML 前置信息是 Claude 决定要不要加载你的技能的依据，务必写对。

**最简格式（够用了）：**

```
---
name: your-skill-name
description: 它干什么。当用户说[具体短语]时使用。
---
```

#### 各字段说明

**`name`（必填）：**

- 只能用 kebab-case
- 没有空格，没有大写
- 最好和文件夹名一致

**`description`（必填）：**

- 必须同时包含：
- 这个技能能做什么
- 什么时候该用（触发条件）
- 最多 1024 个字符
- 不能含 XML 标签（`<` 或 `>`）
- 要包含用户可能实际说出的话
- 如果涉及特定文件类型，要提到

**`license`（可选）：**

- 开源才需要填
- 常见选项：MIT、Apache-2.0

**`compatibility`（可选）：**

- 1-500 个字符
- 说明运行环境要求，比如：目标产品、需要的系统包、是否需要网络访问等

**`metadata`（可选）：**

- 任意键值对
- 推荐写上：author、version、mcp-server

```
---
name: skill-name
description: [必填描述]
license: MIT                                       # 可选：开源协议，如 MIT 或 Apache-2.0
compatibility: Requires Claude.ai with internet    # 可选：环境要求（1-500字符）
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"  # 可选：限制工具访问
metadata:
  author: 公司名称
  version: 1.0.0
  mcp-server: server-name
  category: productivity
  tags: [project-management, automation]
  documentation: https://example.com/docs
  support: [REDACTED_SECRET]
---
```

**安全限制：**

- 禁止用 XML 尖括号（`<` `>`）
- 技能名称不能以 "claude" 或 "anthropic" 开头（保留词）
- 原因：前置信息会进入 Claude 的系统提示，恶意内容可能被用来注入指令

---

### 写好 description 字段

Anthropic 工程博客说过："这段元数据……提供了恰好足够让 Claude 知道该用哪个技能的信息，而不需要把所有内容都加载到上下文里。"这就是渐进式披露的第一层。

**格式模板：`[能做什么] + [什么时候用] + [主要功能]`**

**✅ 好的写法：**

```
# 好——具体且可操作
description: 分析 Figma 设计文件并生成开发者交接文档。
  当用户上传 .fig 文件，或者问"设计规格"、"组件文档"、
  "设计转代码交接"时使用。

# 好——包含触发词
description: 管理 Linear 项目工作流，包括冲刺规划、任务创建和状态追踪。
  当用户提到"冲刺"、"Linear 任务"、"项目规划"，
  或者要求"创建工单"时使用。

# 好——价值主张清晰
description: PayFlow 的端到端客户引导工作流。
  处理账户创建、支付设置和订阅管理。
  当用户说"引导新客户"、"设置订阅"或"创建 PayFlow 账户"时使用。
```

**❌ 不好的写法：**

```
# 太模糊
description: 帮助处理项目。

# 没有触发条件
description: 创建复杂的多页文档系统。

# 太技术化，用户不会这么说
description: 实现具有层次关系的 Project 实体模型。
```

---

### 写主体指令

过了 YAML 前置信息，就用 Markdown 写具体的指令。

**推荐结构：**

```
---
name: your-skill
description: [...]
---

# 你的技能名称

## 指令

### 第 1 步：[第一个主要步骤]
清楚说明这步要做什么。

示例：
```bash
python scripts/fetch_data.py --project-id PROJECT_ID
预期输出：[描述成功时应该看到什么]
```

### 第 2 步：[下一步骤，按需添加]

## 示例

### 示例 1：[常见场景]
用户说："设置一个新的营销活动"
操作：
1. 通过 MCP 获取现有活动
2. 用提供的参数创建新活动
结果：活动创建成功，附上确认链接

## 故障排查

错误：[常见错误消息]
原因：[为什么会出现]
解决方法：[怎么修]
```

**写指令的最佳实践：**

**✅ 要具体，要说清楚怎么操作：**

```
运行 `python scripts/validate.py --input {filename}` 来检查数据格式。
如果验证失败，常见原因有：
- 缺少必填字段（把它加到 CSV 里）
- 日期格式不对（要用 YYYY-MM-DD）
```

**❌ 别含糊其词：**

```
继续之前请先验证数据。
```

**✅ 要包含错误处理：**

```
## 常见问题

### MCP 连接失败
看到 "Connection refused" 时：
1. 确认 MCP 服务器在运行：检查 设置 > 扩展
2. 确认 API 密钥有效
3. 尝试重连：设置 > 扩展 > [你的服务] > 重新连接
```

**✅ 要用渐进式引用：**

```
写查询之前，请先看 `references/api-patterns.md`，里面有：
- 速率限制指南
- 分页模式
- 错误码和处理方式
```

**SKILL.md 要保持聚焦**：核心指令放在 SKILL.md，详细文档移到 `references/` 里，通过链接引用。

---

## 第三章：测试与迭代

你可以根据需要选择不同严格程度的测试方式：

- **在 Claude.ai 里手动测试**——直接跑查询，看行为。迭代快，零配置。
- **在 Claude Code 里用脚本测试**——自动化测试用例，每次改完都能跑一遍验证。
- **通过技能 API 程序化测试**——构建系统化的评估套件，针对预定义测试集运行。

按实际需要选。个人用的小技能和面向数千企业用户的技能，测试严格程度自然不一样。

> 💡 **专业技巧：先把一个难题跑通，再推广**
>
> 我们发现，最高效的做法是：先针对一个最具挑战的任务反复迭代，直到 Claude 成功搞定，再把这个成功方案提炼成技能。这样能充分利用 Claude 的上下文学习能力，比广撒网测试更快得到有效反馈。有了可运行的基础后，再扩展到多个测试用例来验证覆盖面。

### 推荐测试方法

**1. 触发测试**

目标：确保技能在对的时机加载。

```
应该触发：
- "帮我设置一个新的 ProjectHub 工作区"
- "我需要在 ProjectHub 里创建个项目"
- "为 Q4 规划初始化一个 ProjectHub 项目"

不应该触发：
- "旧金山今天天气怎么样？"
- "帮我写个 Python 脚本"
- "创建一个电子表格"（除非你的技能支持表格）
```

**2. 功能测试**

目标：验证技能输出是对的。

```
测试：创建包含 5 个任务的项目
给定：项目名 "Q4 规划"，5 个任务描述
执行：技能运行工作流
验证：
  - ProjectHub 里创建了项目
  - 5 个任务属性都正确
  - 所有任务都关联到项目
  - 没有 API 报错
```

**3. 对比测试**

目标：证明技能比没有技能时更好。

| 指标             | 无技能           | 有技能       |
| ---------------- | ---------------- | ------------ |
| 用户如何提供指令 | 每次都要         | 自动执行     |
| 来回消息数       | 15 条            | 2 个澄清问题 |
| API 调用失败次数 | 3 次（需要重试） | 0 次         |
| 消耗的 token     | 12,000           | 6,000        |

### 用 skill-creator 工具

skill-creator 是一个特殊的技能，内置于 Claude.ai，也可以下载用于 Claude Code。

它能帮你：

**创建技能：**

- 从自然语言描述生成技能
- 自动产生格式正确的 SKILL.md
- 建议触发词和结构

**审查技能：**

- 标出常见问题：描述太模糊、缺少触发条件、结构有问题
- 识别过度/不足触发的风险
- 根据技能目的建议测试用例

**迭代改进：**

- 遇到边缘案例或失败后，把问题带回 skill-creator，让它帮你改进

使用方法：

```
"使用 skill-creator 帮我为[你的用例]构建一个技能"
```

> ⚠️ 注意：skill-creator 帮你设计和打磨技能，但不会跑自动化测试套件，也不会生成量化评估结果。

### 根据反馈持续迭代

技能是"活文档"，要根据实际使用情况不断调整。

**触发不足的信号：**

- 技能该自动加载时没加载
- 用户手动开启它
- 有人问"什么时候用这个技能"

→ 解决办法：在 description 里加更多细节和关键词（包括专业术语）

**触发过度的信号：**

- 技能在不相关的查询里也触发了
- 用户禁用了它
- 用户搞不清它的用途

→ 解决办法：添加负触发词，让描述更具体

**执行问题的信号：**

- 结果不一致
- API 调用失败
- 需要用户帮忙纠正

→ 解决办法：改进指令，加上错误处理

---

## 第四章：发布与分享

技能能让你的 MCP 集成更完整。当用户在比较不同集成方案时，有技能的产品能更快展现价值，比单纯的 MCP 更有竞争力。

### 当前分发方式（2026 年 1 月）

**个人用户怎么获取技能：**

1. 下载技能文件夹
2. 压缩成 zip
3. 通过 Claude.ai 的 设置 > 功能 > 技能 上传
4. 或放到 Claude Code 的技能目录里

**组织级技能：**

- 管理员可以在工作区范围内部署技能（2025 年 12 月 18 日已上线）
- 支持自动更新和集中管理

### 开放标准

Anthropic 已将 Agent Skills 作为开放标准发布。和 MCP 一样，技能应该能跨工具和平台使用——同一个技能不管在 Claude 还是其他 AI 平台上都能用。当然，有些技能可能专门利用了特定平台的能力；作者可以在 `compatibility` 字段里注明这一点。

### 通过 API 使用技能

如果你需要用程序来调用技能（比如构建应用、AI 代理或自动化工作流）：

- 用 `/v1/skills` 接口管理技能
- 在 Messages API 的 `container.skills` 参数里添加技能
- 在 Claude Console 里做版本控制和管理
- 配合 Claude Agent SDK 构建自定义代理

**API 和 Claude.ai 怎么选？**

| 使用场景                 | 推荐方式                |
| ------------------------ | ----------------------- |
| 用户直接使用技能         | Claude.ai / Claude Code |
| 开发时手动测试和迭代     | Claude.ai / Claude Code |
| 个人或临时工作流         | Claude.ai / Claude Code |
| 程序化调用技能的应用     | API                     |
| 规模化生产部署           | API                     |
| 自动化管道和 AI 代理系统 | API                     |

> ⚠️ API 中使用技能需要 Code Execution Tool（代码执行工具）测试版，它为技能运行提供安全环境。

### 今天就能做的事

**第一步：托管到 GitHub**

- 开源技能用公开仓库
- 写清楚 README（供人类查看——这个放仓库根目录，不是技能文件夹里）
- 附上使用示例和截图

**第二步：在 MCP 文档里说明**

- 链接到技能
- 解释 MCP + 技能一起用的价值
- 提供快速上手指南

**安装指南参考模板：**

```
## 安装 [你的服务] 技能

1. 下载技能：
   - 克隆仓库：`git clone https://github.com/yourcompany/skills`
   - 或从 Releases 下载 ZIP

2. 安装到 Claude：
   - 打开 Claude.ai > 设置 > 技能
   - 点击"上传技能"
   - 选择技能文件夹（压缩文件）

3. 启用技能：
   - 打开 [你的服务] 技能的开关
   - 确认 MCP 服务器已连接

4. 测试：
   - 让 Claude："在 [你的服务] 里设置一个新项目"
```

### 怎么介绍你的技能

你描述技能的方式，很大程度上决定了用户愿不愿意用它。

**聚焦结果，而非功能：**

✅ 好的写法：

```
"ProjectHub 技能让团队能在几秒钟内建立完整的项目工作区——
包括页面、数据库和模板——而不是花 30 分钟手动配置。"
```

❌ 不好的写法：

```
"ProjectHub 技能是一个包含 YAML 前置信息和 Markdown 指令
并调用我们 MCP 工具的文件夹。"
```

**讲清楚 MCP + 技能的组合故事：**

```
"我们的 MCP 服务器让 Claude 能访问你的 Linear 项目。
我们的技能教 Claude 你团队的冲刺规划工作流程。
两者结合，实现 AI 驱动的项目管理。"
```

---

## 第五章：模式与故障排查

下面这些模式来自早期采用者和内部团队的真实经验，是我们观察到真正有效的常见做法——不是固定模板，可以灵活用。

### 选你的出发点：问题优先 vs. 工具优先

想象一下去建材超市。你可能带着问题来——"我需要修厨柜"——店员帮你找合适的工具。或者你拿了个新电钻，再想怎么用它完成你的活儿。

技能也是同样的逻辑：

- **问题优先**："我需要设置项目工作区" → 技能按正确顺序协调 MCP 调用。用户说目标，技能搞定工具。
- **工具优先**："我已经连上了 Notion MCP" → 技能教 Claude 最佳工作流程和实践。用户有访问权限，技能提供专业知识。

大多数技能会偏向其中一个方向。搞清楚哪种框架适合你的用例，能帮你选对下面的模式。

### 模式一：顺序工作流编排

**适合场景：** 用户需要按特定顺序执行多个步骤。

```
## 工作流：引导新客户

### 第 1 步：创建账户
调用 MCP 工具：`create_customer`
参数：name, email, company

### 第 2 步：设置支付
调用 MCP 工具：`setup_payment_method`
等待：支付方式验证通过

### 第 3 步：创建订阅
调用 MCP 工具：`create_subscription`
参数：plan_id, customer_id（来自第 1 步）

### 第 4 步：发送欢迎邮件
调用 MCP 工具：`send_email`
模板：welcome_email_template
```

关键技术：步骤顺序要明确、步骤间依赖关系要写清楚、每个阶段要有验证、失败时要有回滚指令。

---

### 模式二：多 MCP 协调

**适合场景：** 工作流需要跨多个服务。

```
## 设计转开发交接

### 阶段一：设计导出（Figma MCP）
1. 从 Figma 导出设计资产
2. 生成设计规格文档
3. 创建资产清单

### 阶段二：资产存储（Drive MCP）
1. 在 Drive 新建项目文件夹
2. 上传所有资产
3. 生成可分享的链接

### 阶段三：创建任务（Linear MCP）
1. 创建开发任务
2. 把资产链接附到任务
3. 分配给工程团队

### 阶段四：发送通知（Slack MCP）
1. 在 #engineering 频道发布交接摘要
2. 附上资产链接和任务引用
```

关键技术：阶段分隔要清晰、MCP 间的数据传递要明确、进下一阶段前要验证、错误处理要集中。

---

### 模式三：迭代式优化

**适合场景：** 输出质量需要通过多轮迭代来提升。

```
## 迭代式报告生成

### 初稿
1. 通过 MCP 获取数据
2. 生成第一稿报告
3. 保存到临时文件

### 质量检查
1. 运行验证脚本：`scripts/check_report.py`
2. 找出问题：
   - 缺失的章节
   - 格式不一致
   - 数据验证错误

### 优化循环
1. 逐一解决发现的问题
2. 重新生成受影响的部分
3. 重新验证
4. 重复，直到达到质量标准

### 最终定稿
1. 应用最终格式
2. 生成摘要
3. 保存最终版本
```

关键技术：质量标准要明确、迭代改进要有节奏、验证脚本要好用、要知道什么时候停。

> 💡 **进阶技巧**：对于关键验证步骤，可以考虑打包一个脚本来做程序化检查，而不是靠自然语言描述。代码的执行是确定的，语言的理解不是。参考 Office 技能系列的示例。

---

### 模式四：情境感知工具选择

**适合场景：** 同一个目标，根据上下文要选不同的工具。

```
## 智能文件存储

### 决策树
1. 检查文件类型和大小
2. 判断最佳存储位置：
   - 大文件（>10MB）：用云存储 MCP
   - 协作文档：用 Notion/Docs MCP
   - 代码文件：用 GitHub MCP
   - 临时文件：用本地存储

### 执行存储
根据决策：
- 调用对应的 MCP 工具
- 应用特定服务的元数据
- 生成访问链接

### 告知用户
说明为什么选了这个存储方式
```

关键技术：决策标准要清晰、要有备用选项、选择理由要透明。

---

### 模式五：特定领域智能

**适合场景：** 你的技能在工具访问之外还需要提供专业知识。

```
## 合规支付处理

### 处理前（合规检查）
1. 通过 MCP 获取交易详情
2. 应用合规规则：
   - 核查制裁名单
   - 验证司法管辖许可
   - 评估风险等级
3. 记录合规决定

### 执行处理
若合规通过：
  - 调用支付处理 MCP 工具
  - 应用适当的反欺诈检查
  - 处理交易
否则：
  - 标记待审核
  - 创建合规案例

### 审计追踪
- 记录所有合规检查
- 记录处理决定
- 生成审计报告
```

关键技术：领域专业知识要嵌入逻辑、行动前要合规检查、记录要完整、治理边界要清晰。

---

### 故障排查

**技能上传失败**

错误："Could not find SKILL.md in uploaded folder"
原因：文件名不是精确的 SKILL.md
解决：重命名，用 `ls -la` 验证确实叫 SKILL.md

错误："Invalid frontmatter"
原因：YAML 格式有问题

```
# 错误——缺少分隔符
name: my-skill
description: Does things

# 错误——引号没闭合
name: my-skill
description: "Does things

# 正确
---
name: my-skill
description: Does things
---
```

错误："Invalid skill name"
原因：名称有空格或大写

```
# 错误
name: My Cool Skill

# 正确
name: my-cool-skill
```

---

**技能不触发**

症状：技能从来不自动加载

解决：修改 description 字段（参考前面的好/坏示例）

自查清单：

- 描述是不是太笼统？（"帮助处理项目"不够用）
- 有没有用户可能实际说的触发词？
- 如果涉及文件类型，有没有提到？

调试技巧：问 Claude："你什么时候会用 [技能名] 这个技能？"Claude 会引用 description 里的内容。根据缺失的部分来调整。

---

**技能触发太频繁**

症状：技能在不相关的查询里也出现了

解决方法：

1. 加负触发词：

```
description: 用于 CSV 文件的高级数据分析，适合统计建模、回归、聚类分析。
  不要用于简单数据探索（请改用 data-viz 技能）。
```

2. 描述更具体：

```
# 太宽泛
description: 处理文档

# 更好
description: 处理 PDF 法律文件以供合同审查
```

3. 明确使用范围：

```
description: PayFlow 电子商务支付处理。专门用于在线支付工作流，
  不适用于一般财务查询。
```

---

**MCP 连接问题**

症状：技能加载了，但 MCP 调用失败

检查清单：

1. 确认 MCP 服务器已连接

- Claude.ai：设置 > 扩展 > [你的服务]
- 应显示"已连接"

2. 检查身份验证

- API 密钥是否有效、是否过期
- 权限/范围是否正确
- OAuth 令牌是否已刷新

3. 单独测试 MCP（不用技能）

- 直接让 Claude 调用 MCP："用 [服务] MCP 获取我的项目"
- 如果这个也失败，问题在 MCP，不在技能

4. 核对工具名称

- 技能里引用的 MCP 工具名称是否正确
- 工具名称区分大小写，一个字母都不能错

---

**指令没有被遵守**

症状：技能加载了，但 Claude 没按指令执行

常见原因及解决方法：

1. **指令太冗长**

- 保持简洁
- 多用列表和编号
- 详细参考文档移到单独文件

2. **关键指令被埋没**

- 重要内容放在最前面
- 用 `## 重要` 或 `## 关键` 这样的标题
- 关键点可以重复

3. **语言模糊**

```
# 不好
确保正确验证相关内容

# 好
关键：在调用 create_project 之前，必须确认：
- 项目名称非空
- 至少分配了一个团队成员
- 开始日期不在过去
```

> 💡 **进阶技巧**：对于关键验证步骤，考虑打包脚本来程序化执行检查，而不是依赖自然语言指令。代码执行是确定的，语言理解不是。参考 Office 技能系列的示例。

4. **模型"偷懒"**——加上明确的激励说明：

```
## 执行说明
- 请花足够时间彻底完成
- 质量比速度更重要
- 不要跳过验证步骤
```

注意：这段加在用户提示里比加在 SKILL.md 里效果更好。

---

**上下文太大导致响应变慢或质量下降**

原因：

- SKILL.md 内容太多
- 同时启用的技能太多
- 所有内容都加载了，没有用渐进式披露

解决方法：

1. 精简 SKILL.md

- 详细文档移到 `references/`
- 用链接引用而非内联
- SKILL.md 尽量控制在 5,000 个词以内

2. 减少同时启用的技能数量

- 超过 20-50 个同时启用的技能就要考虑精简了
- 建议按需选择性启用
- 相关功能可以打包成技能"组合包"

---

## 第六章：资源与参考

如果你是第一次做技能，建议先看最佳实践指南，再根据需要查阅 API 文档。

### 官方文档

**Anthropic 官方资源：**

- Best Practices Guide（最佳实践指南）
- Skills Documentation（技能文档）
- API Reference（API 参考）
- MCP Documentation（MCP 文档）

**官方博客文章：**

- Introducing Agent Skills
- Engineering Blog: Equipping Agents for the Real World
- Skills Explained
- How to Create Skills for Claude
- Building Skills for Claude Code
- Improving Frontend Design through Skills

### 示例技能

**公开技能仓库：**

- GitHub：`anthropics/skills`
- 包含 Anthropic 创建的技能，可以直接自定义用

### 工具和实用程序

**skill-creator 技能：**

- 内置于 Claude.ai，也可用于 Claude Code
- 可以从描述生成技能
- 提供审查和改进建议
- 使用方法："用 skill-creator 帮我构建一个技能"

**验证与评审：**

- skill-creator 也可以评估已有的技能
- 问法："请审查这个技能，并给出改进建议"

### 获取支持

**技术问题：**

- 社区论坛 / Claude Developers Discord

**Bug 报告：**

- GitHub Issues：`anthropics/skills/issues`
- 提交时请包含：技能名称、错误信息、复现步骤

---

## 附录A：快速检查清单

上传技能前后，用这个清单验证一遍。想快点开始的话，可以先用 skill-creator 生成初稿，再过一遍这个清单。

**开始之前**

-   确定了 2-3 个具体用例
-   确定了所需工具（内置还是 MCP）
-   看过这份指南和示例技能
-   规划好了文件夹结构

**开发过程中**

-   文件夹用了 kebab-case 命名
-   `SKILL.md` 文件存在（精确拼写，区分大小写）
-   YAML 前置信息有 `---` 分隔符
-   `name` 字段：kebab-case、无空格、无大写
-   `description` 同时写了"做什么"和"什么时候用"
-   没有 XML 标签（`<` `>`）
-   指令清晰、可操作
-   包含了错误处理
-   提供了示例
-   参考资料有清晰的链接

**上传前**

-   测试了明显任务的触发
-   测试了换一种说法的触发
-   确认不会在不相关主题上触发
-   功能测试通过
-   工具集成正常（如果有）
-   压缩成了 .zip 文件

**上传后**

-   在真实对话里测试过
-   观察了过度/不足触发的情况
-   收集了用户反馈
-   根据反馈迭代了 description 和指令
-   更新了 metadata 里的版本号

---

## 附录B：YAML 前置信息参考

**必填字段**

```
---
name: skill-name-in-kebab-case
description: 它做什么以及什么时候用。包含具体的触发短语。
---
```

**所有可选字段**

```
name: skill-name
description: [必填描述]
license: MIT                  # 可选：开源协议，如 MIT 或 Apache-2.0
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"  # 可选：限制工具访问
compatibility: Requires network access  # 可选：运行环境需求（1-500字符）
metadata:                     # 可选：自定义字段
  author: Company Name
  version: 1.0.0
  mcp-server: server-name
  category: productivity
  tags: [project-management, automation]
  documentation: https://example.com/docs
  support: [REDACTED_SECRET]
```

**安全说明**

允许的：

- 标准 YAML 类型（字符串、数字、布尔值、列表、对象）
- 自定义 metadata 字段
- 较长的 description（最多 1024 个字符）

禁止的：

- XML 尖括号（`<` `>`）——安全限制
- YAML 中执行代码（用的是安全 YAML 解析）
- 以 "claude" 或 "anthropic" 开头的技能名（保留词）

---

## 附录C：完整技能示例

想看展示本指南中各种模式的完整、可生产用的技能？这里有：

- **Document Skills**——PDF、DOCX、PPTX、XLSX 创建
- **Example Skills**——各种工作流程模式
- **Partner Skills Directory**——Asana、Atlassian、Canva、Figma、Sentry、Zapier 等合作伙伴的技能

这些仓库持续更新，示例比本文更丰富。克隆下来，按你的需求改，用作模板。


path: references/checklist.md
content: # Skill 审核检查清单

基于 Anthropic 官方 Skills 开发指南

## 快速审核清单

### 结构检查（4 分）

- [ ] 文件夹用了 kebab-case 命名（如 `my-skill`）
  - ❌ `MySkill` ❌ `my_skill` ❌ `My Skill`
  - ✅ `my-skill`
- [ ] `SKILL.md` 文件存在（精确拼写，区分大小写）
  - ❌ `skill.md` ❌ `SKILL.MD`
  - ✅ `SKILL.md`
- [ ] 无 `README.md` 在技能文件夹内
- [ ] 可选文件夹命名规范（如存在）

**得分：__/4**

---

### 可选文件夹命名（如果存在）

- [ ] `scripts/` - 全小写复数，无空格/下划线
  - ❌ `Scripts` ❌ `script` ❌ `scripts_backup`
  - ✅ `scripts`
- [ ] `references/` - 全小写复数，无空格/下划线
  - ❌ `References` ❌ `reference` ❌ `refs`
  - ✅ `references`
- [ ] `assets/` - 全小写复数，无空格/下划线
  - ❌ `Assets` ❌ `asset` ❌ `asset_files`
  - ✅ `assets`

---

### YAML 前置信息检查

**必填字段验证：**
- [ ] YAML 分隔符完整（开头和结尾都有 `---`）
- [ ] `name` 字段：kebab-case、无空格、无大写
  - ❌ `name: MySkill`  ✅ `name: my-skill`
- [ ] `name` 不以 "claude" 或 "anthropic" 开头
- [ ] `description` 字段存在且非空
- [ ] 无 XML 标签（`<` `>`）

**Description 质量评分（8 分）：**
- [ ] [2 分] 开头说明做什么（主动动词）
  - 好："分析 Figma 设计文件并生成开发者交接文档"
  - 差："这是关于 Figma 的技能"
- [ ] [2 分] 包含触发条件（"当用户...时"）
  - 好："当用户上传 .fig 文件或询问设计规格时使用"
  - 差：无触发条件
- [ ] [2 分] 具体范围（提及具体工具、操作或场景）
  - 好："Figma 设计文件、.fig、组件文档"
  - 差："帮助处理项目"
- [ ] [2 分] 合理长度（50-200 字符，不超过 1024）
  - 太短：无搜索价值
  - 太长：被截断

**得分：__/8**

---

### 组织评分（6 分）

**按任务/场景组织（而非按抽象概念）：**
- [ ] [2 分] 按任务/操作组织章节
  - 好："## 编码和解码" → "## 检查字符" → "## 转换格式"
  - 差："## 理论" → "## 类型" → "## 高级"
- [ ] [2 分] 常见操作优先
  - 好：基础用法 → 变体 → 高级 → 边界情况
  - 差：配置说明 → 理论背景 → 最后才是基础用法
- [ ] [1 分] 章节自包含（可独立使用）
- [ ] [1 分] 深度一致（不混用 h2 与 h4 随机跳转）

**得分：__/6**

---

### 主体指令（6 分）

**必须包含：**
```
[ ] 清晰的工作流程或步骤说明
[ ] 至少一个使用示例
[ ] 错误处理或故障排查指南
```

**推荐包含（不扣分）：**
```
[ ] 预期输出说明
[ ] 多个场景示例
[ ] 参考文档链接
[ ] "使用场景"或"When to Use"部分
```

**得分：__/6**

---

### 示例质量（9 分）

**示例密度计算：**
```
总行数：___
代码块数量：___
密度：每 ___ 行 1 个代码块

参考目标：每 5-30 行 1 个代码块
< 5 行/块：可能过于碎片化（短命令集或多命令速查除外）
> 40 行/块：需要更多示例
```

**示例密度评分：**
```
[3] 密度在 5-30 行/块范围内
[2] 密度略低（30-40 行/块）或略高（3-5 行/块）
[0] 密度严重不足（>40 行/块）或过高（<3 行/块）
```

**每个示例质量评分（0-3 分）：**
```
[ ] 语言标签正确（```bash, ```python 等）
[ ] 语法正确，命令可执行
[ ] 展示了预期输出或结果说明
[ ] 使用真实值（非 foo/bar/baz）
[ ] 无占位符（TODO, FIXME, xxx）
[ ] 自包含或有设置说明

0 分：broken 或有误导性
1 分：可用但简陋（无输出/上下文）
2 分：良好（正确，有输出或说明）
3 分：优秀（可直接复制，真实，覆盖边界）
```

**示例质量得分 = 所有示例平均分 × 密度分 / 3 = __/9**

---

### 可执行性（10 分）

核心问题：Agent 能否按照这些指令产生正确结果？

```
[3] 使用祈使句（"运行 X"、"创建 Y"）
    非："可以考虑..."或"建议..."或"You might..."

[3] 步骤顺序合理（前置条件在行动之前）

[2] 错误处理（说明失败时怎么做）

[2] 输出/结果描述（如何验证成功）
```

**得分：__/10**

---

### 渐进式披露（3 分）

```
[ ] SKILL.md 控制在 500 行以内
    500-600 行：给出提醒，不扣分
    超过 600 行：扣分
[ ] 详细文档是否在 `references/` 中
[ ] 大文件（>300 行）有目录或结构说明
```

**得分：__/3**

---

### Tips 评分（8 分）

**技巧部分质量评估：**

- [ ] [2 分] 5-10 条技巧
  - 少于 5 条：覆盖不足
  - 多于 10 条：可能不够精炼

- [ ] [2 分] 技巧非显而易见
  - 好："Makefile 头号陷阱：缩进必须用 Tab，不能用空格"
  - 差："确保测试你的代码"

- [ ] [2 分] 技巧具体可执行
  - 好："使用 flock 防止 cron 任务重叠执行"
  - 差："小心并发执行"

- [ ] [1 分] 技巧不矛盾主体内容

- [ ] [1 分] 技巧覆盖特定主题的陷阱/踩坑点

**得分：__/8**

---

### （可选）Metadata 参考

> 仅当 skill 包含 metadata 时检查，作为额外参考，不计入总分

- [ ] emoji 与技能主题相关
- [ ] requires 列出技能实际使用的工具
- [ ] os 数组准确
- [ ] JSON 格式有效

（仅供参考，不计分）

---

## 评分总结

```
总分计算：
─────────────────────────────────────
结构检查              __       4
Description 质量       __       8
组织评分              __       6
主体指令              __       6
示例质量              __       9
可执行性              __      10
渐进式披露            __       3
Tips 评分             __       8
─────────────────────────────────────
总计                 __      54

转换为百分制：总分 × 1.85 = ___/100

评级：
  85+  优秀 — 可直接发布
  70-84 良好 — 需要小改进
  50-69 一般 — 需要明显改进
  < 50  较差 — 需要重大修改

结论：{PUBLISH / REVISE / REWORK}
```

---

## 缺陷快速判断

### 严重缺陷（立即阻止发布）

- [ ] YAML 解析错误
- [ ] 缺少 name 或 description 字段
- [ ] 代码示例语法错误
- [ ] 误导性描述（承诺未覆盖的功能）

### 主要缺陷（发布前应修复）

- [ ] 缺少"使用场景"部分
- [ ] 大段文字（>10 行）无示例
- [ ] 示例缺少语言标签
- [ ] 缺少 Tips/技巧部分
- [ ] 按抽象概念组织而非任务

### 次要缺陷（建议修复）

- [ ] 占位符值（foo, bar, TODO）
- [ ] 格式不一致
- [ ] 缺少交叉引用
- [ ] 过时的命令/语法

---

## 快速审核模板

```markdown
## 快速审核：{skill-name}

**结构**：[通过/问题：...]
**Description**：[强/弱：原因]
**示例**：[_ 个代码块，共 _ 行 — 密度 正常/低/高]
**可执行性**：[可以/不可以遵循，因为...]
**首要缺陷**：[最应该修复的问题]
**评分**：__/100
**结论**：[PUBLISH / REVISE / REWORK]
```

---

## 官方指南参考

- `references/anthropic-skills-development-guide.md` - 完整版
- `references/official-guide-summary.md` - 精简版


path: references/official-guide-summary.md
content: # Anthropic 官方 Skills 开发指南 - 精简参考

> **注意**：这是精简版，用于快速查阅常用规范。
> 完整指南请参考：`anthropic-skills-development-guide.md`

---
## YAML 前置信息规范

### 必填字段

```yaml
---
name: skill-name-in-kebab-case
description: 它做什么以及什么时候用。包含具体的触发短语。
---
```

### 可选字段

```yaml
license: MIT                          # 开源协议
allowed-tools: "Bash(python:*) WebFetch"  # 限制工具访问
compatibility: Requires network access    # 运行环境需求（1-500 字符）
metadata:
  author: Company Name
  version: 1.0.0
  mcp-server: server-name
  category: productivity
  tags: [project-management, automation]
```

### 安全限制

**禁止：**
- XML 尖括号（`<` `>`）
- 以 "claude" 或 "anthropic" 开头的技能名

---

## Description 字段最佳实践

### 格式模板

`[能做什么] + [什么时候用] + [主要功能]`

### 好的写法 ✅

```
# 具体且可操作
description: 分析 Figma 设计文件并生成开发者交接文档。
  当用户上传 .fig 文件，或者问"设计规格"、"组件文档"、
  "设计转代码交接"时使用。

# 包含触发词
description: 管理 Linear 项目工作流，包括冲刺规划、任务创建和状态追踪。
  当用户提到"冲刺"、"Linear 任务"、"项目规划"，
  或者要求"创建工单"时使用。

# 价值主张清晰
description: PayFlow 的端到端客户引导工作流。
  处理账户创建、支付设置和订阅管理。
  当用户说"引导新客户"、"设置订阅"或"创建 PayFlow 账户"时使用。
```

### 差的写法 ❌

```
# 太模糊
description: 帮助处理项目。

# 没有触发条件
description: 创建复杂的多页文档系统。

# 太技术化
description: 实现具有层次关系的 Project 实体模型。
```

---

## 文件夹结构

```
your-skill-name/
├── SKILL.md              # 必须
├── scripts/              # 可选
│   ├── process_data.py
│   └── validate.sh
├── references/           # 可选
│   ├── api-guide.md
│   └── examples/
└── assets/               # 可选
    └── report-template.md
```

### 命名规则

**文件夹名：**
- ✅ kebab-case：`notion-project-setup`
- ❌ 空格：`Notion Project Setup`
- ❌ 下划线：`notion_project_setup`
- ❌ 大写：`NotionProjectSetup`

**SKILL.md：**
- ✅ `SKILL.md`（精确，区分大小写）
- ❌ `skill.md`, `SKILL.MD`, `skill-guide.md`

---

## 主体指令最佳实践

### 推荐结构

```markdown
# 你的技能名称

## 指令

### 第 1 步：[第一个主要步骤]
清楚说明这步要做什么。

示例：
```bash
python scripts/fetch_data.py --project-id PROJECT_ID
```
预期输出：[描述成功时应该看到什么]

### 第 2 步：[下一步骤]

## 示例

### 示例 1：[常见场景]
用户说："设置一个新的营销活动"
操作：
1. 通过 MCP 获取现有活动
2. 用提供的参数创建新活动
结果：活动创建成功，附上确认链接

## 故障排查

错误：[常见错误消息]
原因：[为什么会出现]
解决方法：[怎么修]
```

### 组织原则（重要）

**按任务组织，而非按概念：**

✅ 好的组织方式：
```
## 编码和解码
## 检查字符
## 转换格式
## 批量处理
```

❌ 差的组织方式：
```
## 理论概述
## 基本概念
## 高级主题
## 背景介绍
```

**常见操作应该优先：**
- 基础用法 → 变体 → 高级 → 边界情况
- 不要：配置说明 → 理论背景 → 最后才是基础用法

---

### 写作模式

**✅ 要具体，要说清楚怎么操作：**
```
运行 `python scripts/validate.py --input {filename}` 来检查数据格式。
如果验证失败，常见原因有：
- 缺少必填字段（把它加到 CSV 里）
- 日期格式不对（要用 YYYY-MM-DD）
```

**❌ 别含糊其词：**
```
继续之前请先验证数据。
```

**✅ 要包含错误处理：**
```
## 常见问题

### MCP 连接失败
看到 "Connection refused" 时：
1. 确认 MCP 服务器在运行：检查 设置 > 扩展
2. 确认 API 密钥有效
3. 尝试重连：设置 > 扩展 > [你的服务] > 重新连接
```

**✅ 要用渐进式引用：**
```
写查询之前，请先看 `references/api-patterns.md`，里面有：
- 速率限制指南
- 分页模式
- 错误码和处理方式
```

### 示例密度指南

**参考目标：每 5-30 行 1 个代码块**

| 密度 | 评价 |
|------|------|
| 5-30 行/块 | 理想范围 |
| 3-5 行/块 | 略高，可能是短命令集或碎片化 |
| 30-40 行/块 | 略低，考虑增加示例 |
| >40 行/块 | 严重不足，文字太多 |
| <3 行/块 | 过高，可能过于碎片化 |

**说明：**
- 长代码示例（完整函数、配置块）自然会拉高行数，这是合理的
- 短命令集（如 CLI 参数列表）密度高也是正常的
- 多命令速查类型技能（如 cheat sheet）密度可能更高
- 关键是避免大段文字无任何示例

**示例质量检查清单：**
- [ ] 语言标签正确（```bash, ```python 等）
- [ ] 语法正确，命令可执行
- [ ] 展示了预期输出或结果说明
- [ ] 使用真实值（非 foo/bar/baz）
- [ ] 无占位符（TODO, FIXME, xxx）
- [ ] 自包含或有设置说明

### 可执行性指南

**核心问题：Agent 能否按照这些指令产生正确结果？**

**祈使句 vs 建议句：**

✅ 好的写法（祈使句）：
```
运行 X 命令
创建 Y 文件
验证 Z 配置
如果失败，检查...
```

❌ 差的写法（建议句）：
```
你可以考虑运行 X
建议创建 Y
可能需要验证 Z
最好检查一下...
```

**步骤顺序：**
- 前置条件必须在行动之前说明
- 不要假设用户已经知道某些信息

**错误处理：**
- 说明失败时怎么做
- 提供具体的错误消息和解决方法

**结果描述：**
- 说明如何验证成功
- 展示预期输出样例

---

## Tips/技巧部分编写指南

Tips 部分是技能的精华，编码了示例无法传达的专业知识。

### 推荐结构

```markdown
## 技巧

- **最重要的原则** — 为什么它最关键，不遵守会怎样。

- **常见陷阱** — 具体说明陷阱是什么，如何避免。

- **性能优化** — 具体的优化技巧，有前后对比更好。

- **工具匹配** — 检查 requires 与实际使用是否匹配。

- **最佳标准** — 你自己会收藏使用吗？
```

### 好的 Tips ✅

```
- **Description 最重要** — 它占实际影响力的 40% 以上。完美的 skill 配上糟糕的 description 也不会被找到。

- **先数代码块** — 少于 8 个代码块的 skill 几乎总是过于抽象而无用。

- **Makefile 头号陷阱** — 缩进必须用 Tab，不能用空格。

- **使用 flock 防止 cron 任务重叠执行** — 具体工具 + 具体场景。

- **按任务组织 vs 按概念组织** — 这是最关键的结构质量差异。
```

### 差的 Tips ❌

```
- 确保测试你的代码 — 太笼统，没有信息量
- 小心并发执行 — 不够具体，没有说明怎么小心
- 阅读官方文档 — 推卸责任，不是实用技巧
- 保持代码简洁 — 正确的废话
```

### 评分标准（8 分）

| 维度 | 分值 | 说明 |
|------|------|------|
| 5-10 条技巧 | 2 分 | 少于 5 条覆盖不足，多于 10 条不够精炼 |
| 非显而易见 | 2 分 | 不能是常识或正确的废话 |
| 具体可执行 | 2 分 | 有具体工具、方法或场景 |
| 不矛盾主体 | 1 分 | 不能与主体指令冲突 |
| 覆盖陷阱 | 1 分 | 针对特定主题的踩坑点 |

---

## 渐进式披露

三层结构：

1. **第一层（YAML 前置信息）**
   - 每次都会加载到系统提示
   - 内容精简：~100 词
   - 让 Claude 知道"做什么、什么时候用"

2. **第二层（SKILL.md 正文）**
   - 任务相关时加载
   - 理想 <500 行
   - 500-600 行：给出提醒，不扣分
   - 超过 600 行：需要精简
   - 保持聚焦

3. **第三层（references/）**
   - 按需加载
   - 无限制
   - 详细文档放这里

### 组织模式

按领域组织多框架技能：
```
cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md
```

---

## 故障排查指南

### 技能不触发

**症状：** 技能从来不自动加载

**解决：** 修改 description 字段

**自查清单：**
- 描述是不是太笼统？（"帮助处理项目"不够用）
- 有没有用户可能实际说的触发词？
- 如果涉及文件类型，有没有提到？

**调试技巧：**
问 Claude："你什么时候会用 [技能名] 这个技能？"
Claude 会引用 description 里的内容。

---

### 技能触发太频繁

**症状：** 技能在不相关的查询里也出现了

**解决方法：**

1. 加负触发词：
```
description: 用于 CSV 文件的高级数据分析，适合统计建模、回归、聚类分析。
  不要用于简单数据探索（请改用 data-viz 技能）。
```

2. 描述更具体：
```
# 太宽泛
description: 处理文档

# 更好
description: 处理 PDF 法律文件以供合同审查
```

---

### 指令没有被遵守

**常见原因及解决：**

1. **指令太冗长**
   - 保持简洁
   - 多用列表和编号
   - 详细参考文档移到单独文件

2. **关键指令被埋没**
   - 重要内容放在最前面
   - 用 `## 重要` 或 `## 关键` 这样的标题
   - 关键点可以重复

3. **语言模糊**
```
# 不好
确保正确验证相关内容

# 好
关键：在调用 create_project 之前，必须确认：
- 项目名称非空
- 至少分配了一个团队成员
- 开始日期不在过去
```

4. **模型"偷懒"**
```
## 执行说明
- 请花足够时间彻底完成
- 质量比速度更重要
- 不要跳过验证步骤
```

---

## 上下文太大/响应变慢

**原因：**
- SKILL.md 内容太多
- 同时启用的技能太多
- 所有内容都加载了，没有用渐进式披露

**解决方法：**

1. 精简 SKILL.md
   - 详细文档移到 `references/`
   - 用链接引用而非内联
   - SKILL.md 尽量控制在 5,000 词以内

2. 减少同时启用的技能数量
   - 超过 20-50 个就要考虑精简
   - 建议按需选择性启用

---

## 完整技能示例

```markdown
---
name: document-creator
description: 创建专业格式的文档（DOCX、PPTX、XLSX）。
  当用户说"创建文档"、"生成报告"、"制作幻灯片"、
  "导出 Excel"或上传模板文件时使用。
---

# Document Creator

## 工作流程

### 第 1 步：确认需求
- 文档类型（DOCX/PPTX/XLSX）
- 内容主题
- 格式要求

### 第 2 步：创建文档
运行创建脚本：
```bash
python scripts/create_docx.py --title "报告标题" --content "内容"
```

### 第 3 步：输出
保存文档并提供下载链接

## 示例

### 示例 1：创建 Word 文档
用户说："帮我创建一个项目报告文档"
操作：
1. 确认报告标题和章节
2. 运行创建脚本
3. 输出 DOCX 文件

## 故障排查

### 文档创建失败
原因：Python 环境缺失依赖
解决：`pip install python-docx`
```

---

*本文档基于 Anthropic 官方 Skills 开发指南精简整理*


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)