Skill 审查器

Skill 质量审计员。读取目标 SKILL.md 及其附带资源，按基准分（100）+ 附加分（30）双部分体系逐项评分，输出结构化审查报告。

审查 Skill 的价值：description 不精准会导致误触发或漏触发，缺少示例会让 AI 输出不稳定，结构混乱会浪费 Token——这些问题在发布前通过审查发现，比上线后再改成本低得多。

前置依赖：无，本 Skill 可独立使用。

获取 Skill 内容

1. 用户提供文件路径 → read_file 读取。
2. 用户粘贴内容 → 直接使用。
3. 用户给出 Skill 名称 → 搜索 ~/.codebuddy/skills/ 和项目 .codebuddy/skills/。

审查流程

Step 1：收集 Skill 全部内容

1. 读取 SKILL.md 文件。
2. list_dir 列出目录结构，检查 scripts/、references/、assets/ 等子目录。
3. 逐一读取附带资源文件。

检查点：确认已获取全部文件，列出文件清单：

已读取文件：
- SKILL.md (xx 行)
- references/xxx.md (xx 行)
- scripts/xxx.sh (xx 行)
共 N 个文件

Step 2：加载评审标准

读取 references/checklist.md，获取双部分评分体系：

• Part A 基准分（100 分，6 个维度，41 个检查项）：保障输出质量与防止出错混淆
• Part B 附加分（30 分，10 个检查项）：保障工程化和长期维护

检查点：确认 checklist 已加载，包含 Part A（6 个维度共 41 项）和 Part B（10 项）。

Step 3：逐维度评审

按 references/checklist.md 中的 Part A（6 个维度共 41 项，满分 100）和 Part B（10 项，满分 30）逐项打分。每个检查项严格按 checklist 中的"评分要点"评判，不可跳过。

检查点：确认 Part A 6 个维度 + Part B 均已评分，总分加和正确。

Step 4：生成审查报告

必须先读取 references/examples.md，其中包含 4 个等级（优秀/良好/待改进/较差）的完整审查报告示例和 1 个测试用例生成示例。参考其格式和评分尺度，按下方模板输出。

Before/After 示例

示例 1：description 质量问题

输入（被审查 Skill 的 description 片段）：

description: 处理代码迁移

输出（审查结果片段）：

| 检查项 | 得分 | 问题说明 | 修复建议 |
|--------|------|---------|---------|
| D2 功能范围 | 1/4 | 未说明从哪迁到哪 | 写清源和目标技术栈 |
| D3 触发场景 | 0/5 | 无触发关键词 | 补充触发短语，如"迁移 HTTP 客户端" |
| D4 排除边界 | 0/4 | 无排除说明 | 明确不处理的场景 |
| D5 空洞词汇 | 1/3 | "处理"过于笼统 | 改为具体动词如"替换""适配" |

示例 2：结构与指令问题

输入（Skill 目录结构）：

my-skill/
├── SKILL.md          # 800 行，包含完整 API 文档
├── README.md
└── helper.py

输出（审查结果片段）：

| 检查项 | 得分 | 问题说明 | 修复建议 |
|--------|------|---------|---------|
| S5 资源目录 | 0/2 | helper.py 散落在根目录 | 移至 scripts/helper.py |
| S6 无多余文件 | 0/1 | 存在 README.md | 删除或移至 references/ |
| S7 正文长度 | 0/2 | 800 行超 500 行上限 | 拆分 API 文档到 references/api.md |
| I4 Before/After | 0/3 | 纯文字描述，无代码对比 | 补充输入→输出的代码对比 |

不及格审查报告信号

以下特征的审查报告视为不合格，输出前必须自查排除：

• 维度凑数：某维度给了分但没有任何扣分说明，或扣分说明是"基本满足"等空话
• 不算总分：维度得分加和 ≠ 基准/附加总分，或总分与等级不匹配
• 复制 checklist 当建议：修复建议直接照抄 checklist 原文（如"补充触发短语"），未结合被审查 Skill 的具体内容给出针对性方案
• 遗漏扣分项：明显不满足的检查项没有出现在待改进表中
• 反模式漏检：存在 checklist 中列出的反模式但未标记
• 满分项出现在待改进表：得满分的检查项不应出现在"待改进项"表格中

Step 5：生成测试用例（审查完成后询问用户是否需要）

当用户选择"为该 Skill 生成一套测试用例（正例/反例/边界）"时，执行以下操作：

5.1 生成规则

1. 从 Skill 中提取所有场景：
• 从 description 中提取触发关键词和使用场景
• 从正文步骤、分支逻辑、FAQ 中提取所有可能的处理路径
• 从 Few-Shot 示例中提取已覆盖的场景
2. 生成三类测试用例：
• 正例（应触发）：覆盖 Skill 描述的所有功能场景，包括典型用法、同义词变体、不同表述方式
• 反例（不应触发）：与 Skill 主题相关但不在处理范围内的请求
• 边界用例（模糊意图）：可能触发也可能不触发的模糊表述
3. 每个用例包含：用户提问 + 期望的模型返回行为 + 评判标准
4. 覆盖要求：正例至少覆盖 Skill 中每个功能点/步骤/分支各 1 个，反例和边界各至少 3 个

5.2 写入被审查 Skill 的 evaluation 目录

生成测试用例后，必须将结果写入被审查 Skill 的 evaluation/test-cases.md 文件：

1. 确定被审查 Skill 的根目录路径（如 .codebuddy/skills//）。
2. 检查该目录下是否存在 evaluation/ 子目录，不存在则创建。
3. 使用 write_to_file 将生成的测试用例写入 /evaluation/test-cases.md。
4. 如果文件已存在，覆盖写入最新生成的测试用例（每次审查生成的用例应是完整的最新版本）。

检查点：确认文件已写入，输出写入路径：

✅ 测试用例已写入：<skill-dir>/evaluation/test-cases.md

5.3 测试用例输出格式

写入文件和输出到对话中均使用以下格式：

# <Skill 名称> 触发与效果测试用例

基于 Skill 描述的场景生成，共 N 个用例（正例 X / 反例 Y / 边界 Z）。

## 正例（应触发）

| # | 用户提问 | 期望模型行为 | 评判标准 |
|---|---------|-------------|---------|
| 1 | "..." | 触发 Skill，执行... | ①触发 ②... ③... |
| ... | ... | ... | ... |

## 反例（不应触发）

| # | 用户提问 | 期望模型行为 | 评判标准 |
|---|---------|-------------|---------|
| 1 | "..." | 不触发该 Skill | 未触发该 Skill |
| ... | ... | ... | ... |

## 边界用例（模糊意图）

| # | 用户提问 | 可能的模型行为 | 评判标准 |
|---|---------|--------------|---------|
| 1 | "..." | 可能触发也可能不触发 | 如触发应符合规范；不触发也合理 |
| ... | ... | ... | ... |

输出格式

按以下模板输出审查结果。检查明细仅列出未得满分的项，满分项不展示；反模式仅列出存在的项。

## Skill 审查：<Skill 名称>

### 📊 基准分：X / 100（<等级>）｜附加分：Y / 30（<星级>）

#### Part A 基准分

| 维度         | 得分 | 满分 |
|-------------|------|------|
| 描述质量     |  xx  |  20  |
| 结构与格式   |  xx  |  15  |
| 指令质量     |  xx  |  25  |
| Token 效率   |  xx  |  10  |
| 安全性       |  xx  |  10  |
| 防错与稳定性  |  xx  |  20  |

#### Part B 附加分

| 类别         | 得分 | 满分 |
|-------------|------|------|
| 工程管理     |  xx  |  10  |
| 质量保障     |  xx  |   8  |
| 持续改进     |  xx  |   3  |
| 易用性增强   |  xx  |   9  |

### 待改进项（基准分）

| 检查项 | 得分 | 问题说明 | 修复建议 |
|--------|------|---------|---------|
| <编号> <名称> | x/y | <具体问题> | <修复方案> |

### 附加项改进建议

| 检查项 | 得分 | 问题说明 | 修复建议 |
|--------|------|---------|---------|
| <编号> <名称> | x/y | <具体问题> | <修复方案> |

（如果附加分无需改进，输出：✅ 附加项均已满足或不适用）

### 反模式

| 反模式 | 影响 | 修复建议 |
|--------|------|---------|
| <名称> | <影响说明> | <修复方案> |

（如果无反模式，输出：✅ 未检测到反模式）

### 💡 总结

<等级图标> **<等级>**（基准 X 分）<星级>（附加 Y 分）— 一句话结论。最需改进：①xxx ②xxx ③xxx。

---
接下来可以：
1. 根据审查结果帮你修复这些问题
2. 为该 Skill 生成一套测试用例（正例/反例/边界）

具体填充示例见 references/examples.md。

基准分等级标准（摘自 references/checklist.md "评分指南"章节，此处为输出模板速查，权威定义以 checklist 为准）：

附加分星级标准（同上，权威定义见 checklist）：

评分前先加载 references/checklist.md 获取评审标准，参考 references/examples.md 了解不同评分场景的输出示例。

对照检查（发出审查报告前逐条过）

1. 总分算对了？ 基准分 = 6 个维度得分之和，附加分 = 4 个类别得分之和，总分与等级匹配。
2. 每个扣分都有说法？ 待改进表中每项都有"具体问题说明 + 针对性修复建议"，不是复制 checklist 原文。
3. 没遗漏扣分项？ 回看 checklist 41 + 10 项，未得满分的是否全部列入待改进表。
4. 反模式逐条对照过？ 对照 checklist 的"反模式速查表"，存在的已列出，不存在的未强凑。
5. 满分项没出现在待改进表？ 只展示扣分项，满分项不应出现。
6. 修复建议有针对性？ 建议结合被审查 Skill 的具体内容，而非泛泛而谈。

使用规范

• ✅ 检查明细仅列出未得满分的项，满分项不展示
• ✅ 反模式仅列出实际存在的项，不存在则输出"✅ 未检测到反模式"
• ✅ 审查前必须读取 references/checklist.md 和 references/examples.md
• ✅ 对 N/A（不适用）的检查项直接给满分，并在说明中标注"N/A"
• ❌ 不要输出全部 41+10 项的逐条打分明细
• ❌ 不要跳过 references 文件直接凭记忆评分
• ❌ 不要将 checklist 原文照搬作为修复建议
• ❌ 不要为不存在的反模式强行凑数

验证方式

验证本 Skill 输出质量的方法：

1. 格式验证：审查报告是否包含 Part A 维度评分表、Part B 附加评分表、待改进项表、反模式表、总结，格式与 references/examples.md 一致。
2. 评分验证：Part A 6 个维度得分加和是否等于基准总分，Part B 各类别得分加和是否等于附加总分。

```

验证命令：

基准分 = 描述质量 + 结构与格式 + 指令质量 + Token效率 + 安全性 + 防错与稳定性

附加分 = 工程管理 + 质量保障 + 持续改进 + 易用性增强

```

1. 对比验证：用一个已知质量的 Skill（如 references/examples.md 中的示例）做审查，对比输出是否与示例评分接近（±5 分内合理）。
2. 测试用例验证：生成的测试用例是否覆盖了 Skill 描述的所有功能场景，正例/反例/边界三类是否齐全。
3. 文件写入验证：

```bash

# 确认测试用例文件已生成

test -f /evaluation/test-cases.md && echo "✅ 文件存在" || echo "❌ 文件缺失"

# 确认包含三类用例

grep -c "## 正例\|## 反例\|## 边界" /evaluation/test-cases.md

# 预期输出：3

```