Skill auditor

Skill Auditor — Skill 提示词质量审查

概述

本 skill 专门用于审查 SKILL.md 文件的提示词质量。它根据六个评分维度评分， 区分「可自动修复」和「需人工判断」两类问题，输出结构化报告和修改建议。

设计原则：

• 工具负责「判断」，用户负责「内容」
• 能自动修复的直接给出替换文字，不能判断的列入人工清单，说明原因
• 统一修改时不涉及下层领域知识的判断（如阈值、标准条款正确性）

---

Part A — 使用方式

模式一：单个 skill 审查（最常用）

用户提供 skill 名称或路径，或直接粘贴 SKILL.md 内容。

在 Claude Code 里：

# 自动定位文件（$CLAUDE_PROJECT_DIR 由 Claude Code 注入；plugin 场景下 $CLAUDE_PLUGIN_ROOT 也可用）
find "$CLAUDE_PROJECT_DIR/skills/<skill-name>" -name "SKILL.md"

在 claude.ai 里： 请用户粘贴 SKILL.md 的完整内容，或告知文件路径。

---

模式二：全库扫描（仅 Claude Code）

用户说「扫描所有 skill」或「全库审查」时，自动扫描项目内所有已安装 skill：

find "$CLAUDE_PROJECT_DIR/skills" -name "SKILL.md" | sort

逐一审查每个文件，最后输出横向对比表，将总分从低到高排序，让最需要改进的 skill 排在前面。

---

模式三：指定修复（审查后）

审查完成后，用户可说「帮我修复第 X 条」或「自动修复所有可修复问题」。

• 可修复问题：直接输出替换文字，用户粘贴即可
• 不可修复问题：解释原因，说明需要用户提供什么信息才能修复

---

Part B — 六个评分维度

每个维度独立评分（满分如下），加权得出总分（满分 100）。

#	维度	满分	权重	说明
D1	角色定义完整性	20	20%	角色是否具体、有工程深度
D2	触发条件具体性	20	20%	触发词是关键词还是模糊判断，含边界触发声明
D3	幻觉规避规则完整性	20	20%	安全关键场景的核心维度，含局限性声明
D4	输出格式约束强度	15	15%	有格式模板+示例强约束
D5	歧义词密度	15	15%	低信息密度占位词的数量
D6	系统/消息分工 + 数据缺失处理	5	5%	两层分离 + 数据缺失默认动作规则
D7	硬约束清单完整性	5	5%	硬约束是否以独立章节 + NEVER 格式呈现

合格门槛：总分 ≥ 70，且 D3（幻觉规避）≥ 12

---

Part C — 各维度评分细则

D1 — 角色定义完整性（满分 20）

检查位置： SKILL.md 开头的角色声明段落（"你是…" / "You are…"）

评分规则：

得分	条件
20	有角色 + 年限/资质 + 引用的具体标准（如 API-571、IEC 61882）
15	有角色 + 专业领域，但缺年限或具体标准
10	有角色声明，但过于笼统（如「你是工具」）
5	角色声明与 skill 实际功能不匹配
0	无任何角色声明

可自动修复： 缺少角色声明时，根据 skill 的功能描述生成一段标准角色声明模板。

不可自动修复： 年限数字、具体标准名称（需用户确认是否符合实际）。

---

D2 — 触发条件具体性（满分 20）

检查位置： YAML frontmatter 的 description 字段，SKILL.md 正文中触发说明段落

核心判断标准（原则一：触发词要是具体关键词，不能是抽象判断）：

好的触发词示例：

• 「减薄」「PDH」「PSV」「MAWP」 → 具体专业关键词 ✓
• 「当设备类型为 vessel 时」 → 具体条件 ✓

差的触发词示例：

• 「当介质有风险时」 → 需要主观判断 ✗
• 「当情况复杂时」 → 完全不可执行 ✗

评分规则：

得分	条件
20	触发词全部为具体关键词/条件，含「即使用户只说 X 也要触发」的边界说明
15	大多数触发词具体，有 1-2 个模糊词
10	触发词不够具体，一半具体一半模糊
5	主要依赖模糊判断触发
0	无触发条件说明

边界触发检查（补充子项）：

检查 description 字段中是否有「即使用户只说 X，也必须触发」的显式边界声明：

• 有 → 不额外限制得分
• 无 → D2 最高得 15 分（不能得满分 20）

可自动修复： 将模糊触发词替换为对应的具体关键词版本；为缺少边界触发声明的 description 生成标准句式模板。

---

D3 — 幻觉规避规则完整性（满分 20）⚠️ 核心维度

检查位置： 全文搜索以下关键词： 严禁 / 禁止 / NEVER / 不得 / 必须标注 / 宗旨 / [TO VERIFY] / applicable="?" / 数据缺失

这个维度对工程安全类 skill 是关键性维度： 如果 skill 涉及 HAZOP、设备完整性、过程安全、检验规程，D3 < 12 时， 即使总分 ≥ 70，也应在报告开头单独标注「安全风险警告」。

评分规则：

得分	条件
20	有完整的幻觉规避体系，如 Y/D/N/? 标注、basis 必须引用实际数值、禁止臆测
15	有 3 条以上具体的禁止性规则，但无系统性框架
10	有 1-2 条幻觉声明，如「禁止编造数据」
5	仅含蓄的谨慎要求，无明确规则
0	无任何幻觉防控机制

特殊检查项（工程安全层）：

扫描以下高风险组合——若 skill 涉及减薄/止回阀/PDH 等装置，检查是否有 H₂S/含硫介质的主动提示规则：

检查：当介质含减薄/硫油/粗苯时，是否强制触发 H₂S 或毒质风险检查？

局限性声明检查（安全关键 Skill 必查）：

检查是否有独立的「本 Skill 局限性」段落，声明哪些判断超出本 Skill 能力范围、需要合资质工程师确认：

• 有 → 不额外限制得分
• 无，且 Skill 涉及过程安全/设备完整性/法规合规 → D3 最高得 15 分

不可自动修复： 具体的幻觉规避规则内容和局限性声明内容涉及领域知识，只能提供模板框架，由用户填入具体条件。

---

D4 — 输出格式约束强度（满分 15）

检查位置： 全文搜索「格式为：」「示例：」「Example:」「输出JSON格式」「ALWAYS use this template」

核心判断标准（原则三：格式约束比内容要求更可靠）：

只说规则：「请注明依据」 → 弱约束，Claude 可以擦边 → 规则 + 格式 + 例子：「格式为：每X年，依据：API-510 §X.X」 → 强约束 ✓

评分规则：

得分	条件
15	有具体格式模板 + 至少一个完整示例（含占位符说明）
10	有格式模板，但无示例
7	有示例，但格式模板不完整
3	只有文字描述输出要求，无格式或示例
0	无任何输出格式约束

可自动修复： 根据 skill 的功能自动生成格式模板骨架（占位符版本），由用户填入实际字段。

---

D5 — 歧义词密度（满分 15）

检查位置： 全文扫描以下低信息密度占位词：

歧义词列表（中文）— 以下词出现在被审查 skill 的规则/指令文字中时计入惩罚：
全面评估 / 综合解决 / 较高要求 / 适当处理 / 进一步交流 / 相关内容 /
提供全面 / 系统性 / 确保质量 / 偏好 / 到位 / 酌情 / 规范操作

歧义词列表（英文）：
comprehensive / robust / ensure quality / as needed /
further discussion / appropriate / relevant / holistic

评分规则：

得分	条件
15	0 个歧义词
12	1-2 个歧义词，且在非关键位置
8	3-5 个歧义词
4	6-10 个歧义词
0	10 个以上歧义词，或歧义词出现在必须项/规则条款中

可自动修复： 逐条列出每个歧义词的位置和建议替换表达。

---

D6 — 系统/消息分工 + 数据缺失处理（满分 5）

检查位置：

1. 查找是否有两个独立的代码块/章节，分别承担：
   • 系统层（告诉 Claude「怎么想」）：角色、规则、价值判断
   • 消息层（告诉 Claude「怎么说」）：输出格式、字数、示例
2. 查找「数据缺失时的默认动作」表格或清单（关键词：数据缺失 / 缺失信息 / missing / 默认动作 / 暂停）

核心判断标准（原则四）： 两层混在一起 → 修改一个可能会影响另一个 → 两层责任清晰 → 可独立迭代优化 ✓

评分规则：

得分	条件
5	有明确两层结构，互不越责 + 有数据缺失处理规则表/清单
3	有明确两层结构，但无数据缺失处理规则
1	只有一层结构，但内容清晰
0	一层结构且责任混乱，或完全无结构

数据缺失处理规则检查（补充子项）：

检查是否有「当关键输入缺失时，Claude 的默认动作」的明确声明：

• 有 → 不额外限制得分
• 无，且 Skill 有 2 个以上必填输入字段 → D6 最高得 3 分

可自动修复： 分析现有内容，建议哪些段落应移至系统层，哪些应移至消息层；为缺少数据缺失规则的 Skill 生成标准表格模板（占位符版本）。

---

D7 — 硬约束清单完整性（满分 5）

检查位置： 全文搜索是否有独立的硬约束章节（标题含「硬约束 / Hard Constraints / 严禁 / NEVER」）

维度边界说明：

• D3 检查"有没有防幻觉内容规则"（内容层面）
• D7 检查"硬约束是否以独立章节 + NEVER/严禁/必须 格式规范呈现"（结构层面）
• 两者不重叠：一个 Skill 可以有防幻觉内容（D3 得分）但无独立硬约束章节（D7 扣分）

评分规则：

得分	条件
5	有独立的「硬约束」章节，每条以 NEVER/严禁/必须 开头，共 3-10 条
3	有 NEVER/严禁/必须 关键词，但散落在正文各处，未成独立章节
1	仅有隐含约束（如"请注意…""建议…"），无显式硬约束语法
0	无任何约束性规则

可自动修复： 将散落在正文中的 NEVER/严禁/必须 语句提取汇总，生成规范格式的硬约束章节草稿，由用户确认后替换。

不可自动修复： 硬约束的内容合理性（某条 NEVER 是否正确）涉及领域知识，不做评判。

---

Part D — 报告输出格式

审查完成后，必须按以下结构输出报告。

报告结构模板

## Skill 质量审查报告 — [skill 名称]
审查时间：[时间]

### 总分：XX / 100  [通过 / 不通过]
合格门槛：总分 ≥ 70，且 D3（幻觉规避）≥ 12

### 维度得分

| 维度 | 得分 | 满分 | 状态 |
|------|------|------|------|
| D1 角色定义完整性 | XX | 20 | ✅/⚠️/❌ |
| D2 触发条件具体性 | XX | 20 | ✅/⚠️/❌ |
| D3 幻觉规避规则完整性 | XX | 20 | ✅/⚠️/❌ |
| D4 输出格式约束强度 | XX | 15 | ✅/⚠️/❌ |
| D5 歧义词密度 | XX | 15 | ✅/⚠️/❌ |
| D6 系统/消息分工 + 数据缺失处理 | XX | 5 | ✅/⚠️/❌ |
| D7 硬约束清单完整性 | XX | 5 | ✅/⚠️/❌ |

✅ ≥ 80%满分  ⚠️ 50-79%  ❌ < 50%

---

### 🔧 可自动修复的问题（共 X 条）

#### 问题 1 — [维度] [简述]
**位置：** SKILL.md 第 XX 行 / Part X / description 字段
**原文：** `...`
**修改为：** `...`
**修改理由：** [一句话说明，引用对应原则]

（继续列出所有可修复问题）

---

### 🔍 需要你判断的问题（共 X 条）

#### 问题 1 — [维度] [简述]
**问题描述：** ...
**为什么不能自动修复：** 涉及 [领域知识/客户习惯/业务逻辑]，你是工具更了解正确答案
**建议方向：** ...
**你需要提供：** ...

（继续列出所有人工判断项）

---

### 📈 改进优先级建议

1. 优先修复：[最高影响的问题]
2. 其次处理：[中等影响]
3. 可以缓：[低影响]

---

Part E — 全库扫描横向对比表（仅 Claude Code 模式）

扫描完所有 skill 后，输出对比表：

## 全库扫描结果

| Skill 名称 | D1 | D2 | D3 | D4 | D5 | D6 | D7 | 总分 | 状态 | 最弱维度 |
|-----------|----|----|----|----|----|----|-----|------|------|---------|
| hazop-analysis | 20 | 18 | 18 | 12 | 13 | 4 | 3 | 88 | ✅通过 | D6,D7 |
| equipment-degradation-proforma | 20 | 17 | 20 | 14 | 11 | 4 | 4 | 90 | ✅通过 | D5 |
| equipment-workorder | 15 | 14 | 0  | 10 | 10 | 3 | 1 | 53 | ❌不通过 | D3⚠️ |
| e-logistic-calculator | 10 | 12 | 0  | 8  | 9  | 2 | 1 | 42 | ❌不通过 | D1,D3 |
| ...       | .. | .. | .. | .. | .. | .. | ..  | ..   | ..   | .. |

⚠️ D3 标注：涉及安全关键功能的 skill，D3=0 需优先处理

总分由低到高排序，让最需要改进的 skill 排在前面。

---

Part F — 幻觉规避规则（本 skill 自身）

1. 评分必须引用 SKILL.md 中的实际文字作为依据，禁止凭印象评分
2. 「歧义词」判定必须精确匹配词表，不得随意扩大范围
3. 「可自动修复」的建议文字必须标注「模板框架，请用户确认细节」
4. 不得对下层领域知识的正确性做出判断（如某个温度阈值对不对）
5. D3 评分低于 12 时，即使总分合格，必须在报告开头单独标注安全警告
6. 如果 SKILL.md 内容不完整（如只有前半段），必须说明「内容不完整，以下评分仅基于已提供部分」

---

Part G — 测试用例（在 Claude Code 里运行）

开发完成后，用以下三个测试提示词验证 auditor 表现：

{
  "skill_name": "skill-auditor",
  "evals": [
    {
      "id": 1,
      "prompt": "帮我审查一下 hazop-analysis 这个 skill 的提示词质量",
      "expected_output": "输出含六维度评分表、可修复问题列表、人工判断清单"
    },
    {
      "id": 2,
      "prompt": "扫描所有 skill，看哪个最需要改进",
      "expected_output": "输出全库横向对比表，总分排序，D3=0 的标注安全警告"
    },
    {
      "id": 3,
      "prompt": "帮我把 e-logistic-calculator 可以自动修复的问题都修复了",
      "expected_output": "列出每个可修复问题的原文和替换文字，不修改其他内容"
    }
  ]
}

---

参考：评分原则来源

本 skill 的评分逻辑基于以下四条经过实践验证的提示词设计原则：

• 原则一（触发具体性）： 触发条件必须是可执行的具体关键词或条件，不能依赖主观判断
• 原则二（默认安全出口）： 数据缺失时标问号，不沉默、不臆测——对安全关键场景尤为重要
• 原则三（格式约束）： 给定规则+格式+示例三件套，比只给规则约束力高 10 倍
• 原则四（分层责任）： 系统指令管「怎么想」，消息模板管「怎么说」，分开才能独立迭代