skill-forge-review

技能审查与验证

流程

步骤 1：定位技能文件

接受以下输入：

• 技能目录的路径
• 技能名称（在 ~/.claude/skills/ 中搜索）
• GitHub 仓库的 URL

读取所有 .md 文件、脚本和资源文件。

步骤 2：结构验证

运行 python scripts/validate_skill.py <path> 执行程序化检查。

手动验证：

• SKILL.md 存在（大小写完全一致）
• 技能文件夹内没有 README.md
• 文件夹名称与 name 字段一致
• 命名符合有效的 kebab-case 格式（1-64 个字符）
• 名称中不包含 "claude" 或 "anthropic"

步骤 3：Frontmatter 审核

检查项	通过标准
名称格式	kebab-case，1-64 个字符，开头和结尾不能是连字符
提供描述	非空，1-1024 个字符
描述包含 WHAT	说明具备哪些能力
描述包含 WHEN	包含触发短语
描述包含关键词	包含领域专用词汇
不含 XML 标签	不包含 < 或 > 字符
可选字段有效	license、compatibility（<500 个字符）、metadata

步骤 4：触发分析

评估描述的触发质量：

触发不足的风险：

• 过于笼统（“帮助处理项目”）
• 缺少常见的转述表达
• 没有领域关键词
• 缺少文件类型说明（如适用）

过度触发的风险：

• 范围过宽（“处理文档”）
• 与 Claude 内置能力重叠
• 缺少用于消歧的负向触发条件

生成测试查询：

• 5 个应该触发该技能的查询
• 5 个不应该触发的查询
• 3 个边界情况（含糊不清的查询）

步骤 5：指令质量

标准	评分（0-10）
具体性	指令是否可执行？（而非“妥善验证”）
完整性	是否涵盖所有工作流？
错误处理	是否处理了常见故障？
示例	是否提供了具体示例？
渐进式披露	详细文档是否放在 references/ 而非 SKILL.md 中？
长度	是否少于 500 行 / 5000 个词元？
交叉引用	指向 references/scripts 的链接是否清晰？

步骤 6：架构审查（多技能）

对于包含子技能的技能：

• 主技能有清晰的路由表
• 子技能的职责明确且聚焦
• 交叉引用有效（文件存在）
• 命名遵循 parent-child 约定
• 共享参考资料放在父级，而非重复存放
• Agent 的角色明确（如属于第 4 层）

步骤 7：脚本质量（如有）

• 文档字符串说明用途、输入和输出
• CLI 接口（argparse 或类似工具）
• 结构化输出（JSON）
• 错误处理（try/except 并提供清晰的消息）
• 没有硬编码路径或密钥
• 依赖项尽可能少

步骤 8：生成技能健康度评分

评分方法（0-100）：

类别	权重	检查项
Frontmatter 质量	25%	名称、描述、格式
触发准确性	20%	WHAT + WHEN + 关键词
指令质量	25%	具体性、完整性、示例
结构合规性	15%	文件命名、组织结构、参考资料
脚本质量	10%	如适用（不需要脚本时得满分）
渐进式披露	5%	是否恰当使用三级系统

步骤 9：生成触发评测集

审核后，生成结构化的触发评测集，用于持续测试：

1. 运行 python scripts/generate_eval_set.py <path>，自动生成初始评测集
2. 审核并优化生成的查询：
   • 确保 8-10 条应该触发的查询涵盖不同措辞和边缘情况
   • 确保 8-10 条不应该触发的查询属于近似匹配（而非明显无关）
   • 在应该触发的查询集中加入口语表达、拼写错误和不常见的领域用法
3. 将评测集保存到技能目录中的 evals/evals.json

好的查询应当真实且具体（包含文件路径、上下文和领域细节）。 不好的查询过于笼统（如“格式化这些数据”）或明显无关。

4. 运行 python scripts/optimize_description.py <path> --eval-set evals/evals.json 为当前描述打分并获取改进建议
5. 建议运行 /skill-forge eval <path> 进行完整的功能评测

步骤 10：生成报告

# Skill Review: [name]

## Health Score: [X]/100

## Summary
[2-3 sentence assessment]

## Scores by Category
| Category | Score | Notes |
|----------|-------|-------|
| Frontmatter | X/25 | [issues] |
| Triggering | X/20 | [issues] |
| Instructions | X/25 | [issues] |
| Structure | X/15 | [issues] |
| Scripts | X/10 | [issues] |
| Disclosure | X/5 | [issues] |

## Critical Issues (fix immediately)
- [issue 1]
- [issue 2]

## High Priority (fix within 1 week)
- [issue 1]

## Recommendations
- [suggestion 1]
- [suggestion 2]

## Suggested Test Queries
### Should Trigger
1. [query]
2. [query]
3. [query]

### Should NOT Trigger
1. [query]
2. [query]
3. [query]