# Skill Auditor

> Skill 提示词质量审查工具。当用户想检查、评估或改进任何 SKILL.md 文件的提示词质量时， 立即使用本 skill。触发关键词包括：审查 skill、检查提示词、skill 质量、SKILL.md 评估、 提示词有没有问题、帮我看这个 skill、skill auditor、audit skill、优化 skill 提示词、 全库扫描、扫描所有 skill。 即使用户只是说「帮我看这个 skill 好不好」也必须触发本 skill。 本 skill 输出结构化质量报告，自动修复可修复问题，并生成「待人工确认」清单。

- Skill: `jihonghe68/skill-auditor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jihonghe68/skill-auditor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jihonghe68/skill-auditor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: jihonghe68 (https://skillmd.com/u/jihonghe68)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jihonghe68/skill-auditor

---


# Skill Auditor — Skill 提示词质量审查

## 概述

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

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

---

## Part A — 使用方式

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

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

**在 Claude Code 里：**
```bash
# 自动定位文件（$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：

```bash
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 表现：

```json
{
  "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 倍
- **原则四（分层责任）：** 系统指令管「怎么想」，消息模板管「怎么说」，分开才能独立迭代