--- 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: "" # ❌ 空描述 # ❌ 包含 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 的一个章节。 - **最佳标准：你自己会收藏使用吗** — 如果你自己不会用，就不要发布。