skill-auditor

检测SKILL.md的指令遵循质量，自动判断skill类型，基于适用维度逐项评分并给出改进建议。触发词：审阅skill、检查skill、skill合规、优化skill

Skill Auditor — SKILL.md 防丢机制检测

检测SKILL.md是否有防丢机制，预防AI执行时丢失关键环节和约束。面向skill使用者和作者。

---

反合理化守卫

以下理由都不是跳过审阅的合法借口：

• ❌ "这个skill看起来没问题" → 必须逐项检查，不能笼统说通过
• ❌ "skill太短不需要审阅" → 短skill也有适用维度，参考型也需要检查渐进式加载
• ❌ "我之前审阅过了" → skill会更新，每次都要重新检查
• ❌ "这个维度不重要" → 由类型映射表决定哪些维度适用，不是你来判断

执行流程与门禁

text

读取SKILL.md
  ↓
🛑G0 展示：skill名称+类型判断+适用维度数 → 等用户确认
  ↓
运行 audit_skill.py 获取客观评分
  ↓
🛑G1 展示：脚本评分结果 → 确认是否需要AI补充主观判断
  ↓
AI逐项补充主观判断（脚本无法检测的维度）
  ↓
生成评分报告 + 改进建议

门禁	触发条件	必须做	禁止做
G0	读取SKILL.md后	展示类型判断结果和适用维度清单	直接出完整报告
G1	脚本运行后	展示客观评分结果	跳过脚本直接AI主观判断

反合理化：如果发现自己在想"这个skill很简单，不需要跑脚本"，立刻停下。脚本给出的客观评分是主观判断的基础，不能跳过。

触发条件

用户提到：审阅skill、检查skill质量、skill合规检测、优化skill、skill-auditor

输入

一个SKILL.md文件路径（必须是已存在的skill）

---

Step 1：自动判断skill类型

读取SKILL.md内容，按以下规则自动判断：

判断条件	类型
有明确的步骤流程（Step1→Step2→...）或门禁表（G0/G1/...）或决策流程图	工作流型
包装了一个脚本/工具，有scripts/目录或CLI命令	工具型
内容是知识/清单/速查表/设计规范，没有步骤流程	参考型
内容是思维方式/方法论/分析框架，不产出具体产物	模式型

优先级：工作流型 > 工具型 > 参考型 > 模式型（如果同时满足多个条件，取优先级最高的）

Step 2：选择适用维度

维度	工作流型	参考型	模式型	工具型
1. 反合理化守卫	✅	—	⚠️	✅
2. 阶段门禁	✅	—	—	⚠️
3. 自动化验证	✅	—	—	✅
4. 决策流程图	✅	—	⚠️	⚠️
5. 陷阱清单	✅	⚠️	—	✅
6. 渐进式加载	✅	✅	✅	✅
7. 三层架构	⚠️	⚠️	—	—
8. Runtime Hooks	⚠️	—	—	✅
9. Context Engineering	✅	✅	✅	✅
10. Scoped Rules	⚠️	⚠️	—	—

✅ = 必须检查，缺失则判❌ ⚠️ = 可选检查，缺失不扣分，有则加分 — = 不适用，跳过不显示

Step 3：逐项检查

只检查Step2中标记为✅或⚠️的维度。标记为—的维度直接跳过，在报告中不显示。

---

维度1：反合理化守卫

达标条件：

• 有明确的"以下理由不是跳过借口"章节或段落
• 每条借口都有具体的反驳理由（不是泛泛的"必须遵守"）
• 借口来自实际踩坑（有日期、有案例）

部分达标： 有"必须做X"的指令，但没有列出AI可能的借口 缺失： 没有任何关于跳过步骤的约束

维度2：阶段门禁

达标条件：

• 有明确的门禁表（G0/G1/G2...或等效的STOP标记）
• 每个门禁有"必须做"和"禁止做"两列
• 门禁之间有依赖关系

部分达标： 有"等用户确认"的提示，但没有结构化的门禁表 缺失： 没有任何停止点，AI可以一口气跑完

维度3：自动化验证

达标条件：

• 有scripts/目录下的验证脚本
• 脚本返回非零退出码表示不通过
• skill中明确要求"运行脚本X验证，不通过则修改后重跑"

部分达标： 提到了验证但没有实际脚本 缺失： 没有验证脚本，依赖AI自我报告

维度4：决策流程图

达标条件：

• 有ASCII流程图或Mermaid图
• 每个分支条件明确
• 有"失败→停止"的规则

部分达标： 有步骤列表但没有分支条件 缺失： 纯自然语言描述

维度5：陷阱清单

达标条件：

• 有⚠️标记的陷阱条目
• 每条包含：具体日期、错误描述、验证方法
• 条目数量≥5

部分达标： 有少量提醒但没有结构化的陷阱清单 缺失： 没有陷阱清单

维度6：渐进式加载

达标条件：

• 有分层设计（触发条件在前、详细规范在后、参考资料在references/）
• 核心规则在skill前200字内
• 详细内容放在references/或templates/目录下

部分达标： 有references/目录但没有明确的分层策略 缺失： 所有内容平铺在一个文件中

维度7：三层架构

达标条件：

• skill明确说明它属于哪一层
• 说明了与AGENTS.md的关系
• 如果需要外部数据，说明了数据源

部分达标： skill独立存在但没有说明与其他层的关系 缺失： 试图在一个文件里承载所有信息

维度8：Runtime Hooks

达标条件：

• 有scripts/目录下的hook脚本
• 或说明了在哪些平台可以使用runtime hooks
• 有"事前拦截"而非"事后检查"的机制

部分达标： 有脚本但是事后验证 缺失： 纯文本指令，没有任何代码层面的强制

维度9：Context Engineering

达标条件：

• skill总字数合理（核心规则<5000字）
• 关键规则前置（前200字内有核心指令）
• 没有冗余重复

部分达标： 长度合理但关键规则位置不理想 缺失： 过长（>10000字核心内容）或关键规则埋在中间

维度10：Scoped Rules

达标条件：

• 有"如果X则加载Y"的条件逻辑
• 或skill被拆分成多个子文件
• 不同场景有不同的规则集

部分达标： 有简单的if-else但没有拆分文件 缺失： 所有规则始终全部加载

---

Step 4：输出报告 + 改进方案

报告必须包含两部分：评分和具体改进方案。只报问题不给方案 = 没有价值。

text

## Skill审阅报告：{skill_name}
类型：{自动判断的类型}（{判断依据}）
适用维度：{N}/10

| # | 维度 | 评分 | 说明 |
|---|------|------|------|
| ... | （只显示适用维度） |

总分：X/10 ✅，Y/10 ⚠️，Z/10 ❌

### 改进方案（按优先级排序）

1. **[最高优先级]** {缺失的防丢机制}
   - 现状：{当前skill里有什么/缺什么}
   - 风险：{AI执行时会怎么丢失}
   - 怎么补：{具体应该加什么内容，给出示例模板或参考}
   - 参考：{哪个现有skill的写法值得借鉴}

改进方案的质量标准：

• 不是泛泛的"建议加反合理化守卫"，而是给出这个skill场景下应该列出哪些具体借口
• 不是"参考Superpowers的写法"，而是给出可以直接修改的模板
• 风险描述要具体："AI执行时会在XX环节跳过XX步骤"，不是"可能有问题" | 文件 | 内容 | |------|------| | references/skill-publishing-guide.md | Skill发布指南：GitHub仓库创建、skills.sh/SkillsMP自动索引、Toolsail手动提交。发布新skill时参考。 |

Pitfalls

1. 不要只看格式不看内容：有"反合理化守卫"章节名不代表真的有效，要看借口列表是否具体
2. 不要忽略references/目录：很多skill的核心知识在references/里，SKILL.md只是入口
3. 平台差异：Runtime Hooks在Hermes中不原生支持（用terminal脚本替代），在Cursor中用.cursor/rules/，在Claude Code中用CLAUDE.md
4. skill大小：SKILL.md本身>5000字说明可能需要拆分，但references/下的文件可以更长
5. ⚠️ 类型判断不是非此即彼（2026-08-19实测）：有些skill同时有工作流和参考特征（如ai-frontier-notes既有步骤流程又有大量参考文档）。此时按优先级取工作流型，但参考型的维度（渐进式加载、Context Engineering）仍然必须检查
6. ⚠️ 短skill不是低质量skill（2026-08-19实测）：一个200字的参考型skill如果触发条件精准、内容分层合理，就是高质量的。不要因为字数少就降低评分标准