Skill Reviewer

依据 Anthropic 官方 Skills 开发指南，对技能进行全面审核。提供结构化审核框架、评分系统、缺陷检查清单和改进建议。

核心职责

结构验证 - 检查文件夹结构、文件命名规范
YAML 审核 - 验证前置信息格式和必填字段
描述评估 - 检查触发条件是否清晰
组织评分 - 评估技能是否按任务组织、常见操作优先
指令审查 - 评估主体指令的质量和完整性
示例质量 - 评估示例密度和可执行性
Tips 评分 - 评估技巧部分的质量和价值
最佳实践 - 对照官方指南检查合规性

工作流程

第 1 步：接收审核请求

当用户请求审核 skill 时：

确认 skill 文件夹路径或读取 SKILL.md 内容
判断审核严格程度：

严格模式（必须读取完整版官方指南）： 当用户表达以下意图时，必须先读取 references/anthropic-skills-development-guide.md 完整版指南：

明确要求"严格检查"、"仔细审核"、"全面审查"
提到"高质量要求"、"生产级别"、"发布前检查"
表达"不想有任何遗漏"、"按最高标准"
用于团队/组织/公司项目
准备公开发布或分享给他人

常规模式：

优先读取 references/checklist.md（快速检查清单）
遇到疑问或边缘案例时读取完整版官方指南

第 2 步：结构检查

文件夹结构验证：

[ ] 技能文件夹使用 kebab-case 命名（如 my-skill）
[ ] SKILL.md 存在且命名精确（区分大小写）
[ ] 无 README.md 在技能文件夹内
[ ] 可选文件夹（如存在）命名规范

可选文件夹命名规范（如存在）：

scripts/ - 全小写复数，无空格/下划线
references/ - 全小写复数，无空格/下划线
assets/ - 全小写复数，无空格/下划线

❌ 错误示例： Scripts、script、scripts_backup、References、refs、Assets、asset_files

评分：__/4

第 3 步：YAML 前置信息检查

必填字段验证：

[ ] name 字段存在，kebab-case，无空格大写
[ ] description 字段存在，非空
[ ] YAML 分隔符完整（--- 开头和结尾）
[ ] 无 XML 标签（< >）
[ ] name 不以 claude/anthropic 开头

Description 质量评分（满分 8 分）：

[2] 开头说明做什么（主动动词）
    好："分析 Figma 设计文件并生成开发者交接文档"
    差："这是关于 Figma 的技能"

[2] 包含触发条件（"当用户...时"）
    好："当用户上传 .fig 文件或询问设计规格时使用"
    差：无触发条件

[2] 具体范围（提及具体工具、操作或场景）
    好："Figma 设计文件、.fig、组件文档、设计交接"
    差："帮助处理项目"

[2] 合理长度（50-200 字符，不超过 1024）
    太短：无搜索价值
    太长：被截断

评分：__/8

第 4 步：组织评分

按任务/场景组织（而非按抽象概念）：

[2] 按任务/操作组织章节
    好："## 编码和解码" → "## 检查字符" → "## 转换格式"
    差："## 理论" → "## 类型" → "## 高级"

[2] 常见操作优先
    好：基础用法 → 变体 → 高级 → 边界情况
    差：配置说明 → 理论背景 → 最后才是基础用法

[1] 章节自包含（可独立使用）

[1] 深度一致（不混用 h2 与 h4 随机跳转）

评分：__/6

第 5 步：主体指令检查

必须包含：

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

推荐包含（不扣分）：

[ ] 预期输出说明
[ ] 多个场景示例
[ ] 参考文档链接
[ ] "使用场景" 或 "When to Use" 部分

评分：__/6

第 6 步：示例质量评估

示例密度计算：

总行数：___
代码块数量：___
密度：每 ___ 行 1 个代码块

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

示例密度评分：

[3] 密度在 5-20 行/块范围内
[2] 密度略低（20-30 行/块）或略高（3-5 行/块）
[0] 密度严重不足（>30 行/块）或过高（<3 行/块）

每个示例质量评分（0-3 分）：

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

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

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

第 7 步：可执行性评估

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

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

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

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

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

评分：__/10

第 8 步：渐进式披露检查

[ ] SKILL.md 控制在 500 行以内
[ ] 详细文档是否在 `references/` 中
[ ] 大文件（>300 行）有目录或结构说明

评分：__/3

第 9 步：Tips 评分

技巧部分质量评估：

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

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

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

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

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

评分：__/8

（可选）Metadata 参考

仅当 skill 包含 metadata 字段时检查，仅供参考，不计分

[ ] emoji 与技能主题相关
[ ] requires.anyBins 列出技能实际使用的工具（非 generic 如 bash）
[ ] os 数组准确（不包含不支持的平台）
[ ] JSON 格式有效

评分总结

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}

常见缺陷

严重缺陷（阻止发布）

缺陷：YAML 前置信息无效
检测：YAML 解析错误、缺少必填字段
修复：验证 YAML 格式，确保 name/description 都存在

缺陷：代码示例损坏
检测：语法错误、未定义变量、错误参数
修复：在干净环境中测试每个命令

缺陷：工具要求不匹配（如存在 metadata）
检测：requires 列出内容未在内容中使用
修复：grep 内容提取命令名，更新 requires 匹配

缺陷：误导性描述
检测：描述承诺的内容实际未覆盖
修复：使描述与实际内容一致，或补充缺失内容

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

缺陷：缺少"使用场景"部分
影响：Agent 不知道何时激活技能
修复：添加 4-8 条触发场景说明

缺陷：大段文字无示例
检测：任何超过 10 行无代码块的章节
修复：为每个概念添加具体示例

缺陷：示例缺少语言标签
检测：``` 后无语言标识符
修复：为每个代码块添加 bash/python/javascript/yaml 等

缺陷：缺少 Tips/技巧部分
影响：缺少使技能有价值的经验总结
修复：添加 5-10 条非显而易见的实用技巧

缺陷：按抽象概念组织
检测：章节名为"理论"、"概述"、"背景"、"介绍"
修复：按任务/操作重组：用户要做什么

次要缺陷（建议修复）

缺陷：占位符值
检测：foo, bar, baz, example.com, TODO, FIXME
修复：替换为真实值

缺陷：格式不一致
检测：混合标题级别、代码块样式不一致
修复：统一标题层次和格式

缺陷：缺少交叉引用
检测：提到其他技能覆盖的工具/概念但未引用
修复：添加"参见 X 技能了解更多"注释

缺陷：过时的命令
检测：旧语法或已弃用工具
修复：更新为当前工具版本和语法

对比审核

当比较同类型技能时：

对比维度：

1. 覆盖广度
   哪个技能覆盖更多用例？

2. 示例质量
   哪个有更多可运行的真实示例？

3. 常见操作深度
   哪个更好地处理 80% 常见场景？

4. 边界情况覆盖
   哪个解决了更多潜在问题和陷阱？

5. 跨平台支持
   哪个适用于更多环境？

6. 时效性
   哪个使用当前工具版本和语法？

胜出者：{技能 A / 技能 B / 平局}
理由：{1-2 句说明}

快速审核模板

当不需要完整评分时的快速审核：

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

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

审核工作流

发布前自查

# 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+

审核他人技能

# 安装技能（如适用）
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"

操作：

读取 ./skills/china-holidays/SKILL.md
判断审核模式（默认常规）
按照评分卡逐项检查
生成审核报告
解读结果并提供改进建议

结果： 输出完整审核报告，包含问题列表、修改建议和最终评分

示例 2：严格模式审核

用户说： "这个 skill 准备发布到团队内部使用，需要严格检查，不能有任何问题"

操作：

触发严格模式
必须先读取 anthropic-skills-development-guide.md
对照官方指南逐项严格检查
输出详细报告，确保无遗漏

示例 3：快速检查 description

用户说： "这个 skill 的 description 写得怎么样？" + 附上内容

操作：

聚焦 description 字段分析
使用 8 分评分标准
提供改进建议

结果： 指出问题并提供修改建议

技巧

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 的一个章节。
最佳标准：你自己会收藏使用吗 — 如果你自己不会用，就不要发布。

skill-reviewer

Skill Reviewer

核心职责

工作流程

第 1 步：接收审核请求

第 2 步：结构检查

第 3 步：YAML 前置信息检查

第 4 步：组织评分

第 5 步：主体指令检查

第 6 步：示例质量评估

第 7 步：可执行性评估

第 8 步：渐进式披露检查

第 9 步：Tips 评分

（可选）Metadata 参考

评分总结

常见缺陷

严重缺陷（阻止发布）

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

次要缺陷（建议修复）

对比审核

快速审核模板

审核工作流

发布前自查

审核他人技能

参考文件

示例

示例 1：完整审核

示例 2：严格模式审核

示例 3：快速检查 description

技巧