把你的 AI skill 丢给这套十步清单，查出「读不到、翻不到、走不通」的结构病。
一个 AI skill 结构体检清单。你的 skill 可能看起来很完整但实际用不了：
- references/ 里躺着写好的文件，正文却从没链接它 → 读者永远翻不到
- 正文引用了某个文件，文件根本不存在 → 断裂引用
- 「XX 文件第 N 行规定 Y」——去查，第 N 行根本不是这句话 → 虚假权威声称
- 异常解法写在文件尾部 300 行处，触发点在第 1 行 → 读者卡死了都不知道有解法
- SKILL.md 说工作流吃 JSON，脚本只吃 HTML → 文档与脚本割裂
这些病，静态检查（看结构、查格式）全部查不出来——只有按清单一步步体检才能暴露。
| # | 检查项 | 查什么 |
|---|---|---|
| 1 | 通读 SKILL.md + 全部 references | 中文 UTF-8 文件被误判 Binary 的坑（用 python 读） |
| 2 | 引用完整性交叉检查 ⭐ | 孤儿 references（有文件没链接）/ 断裂引用（有链接没文件） |
| 3 | 错位文件检测 | 内容属于别的 skill 的错位文件 |
| 4 | 重复/残留章节 | 迭代中粘贴残留：完整版 + 半成品并存 |
| 5 | 代码块配对 | 未闭合 ``` 会把后续整节渲染成代码 |
| 6 | 删除前迁移检查 | 独有信息先归位再删副本 |
| 7 | 权威声称核实 ⭐ | 「X 文件第 N 行规定 Y」逐条验证——声称的权威可能不存在 |
| 8 | 兜底前向引用 | 异常解法写在尾部，触发点在入口——读者不知道有兜底 |
| 8b | 文档/脚本一致性 | 文档说 JSON 工作流、脚本只吃 HTML |
| 8c | 触发词一致性 | frontmatter triggers vs 正文触发词漂移 |
| 8d | 架构改造后旧口径对账 | 改造后旧表述残留在漏改位置 |
⭐ = 实战中抓出过真 bug、且通用工具查不出的高价值项。
对你的 AI 助手说一句话：
「帮我检查一下 XX skill 的结构健康」
或直接跑自动化脚本（覆盖第 2/4/5 步）：
python3 scripts/audit_skill_health.py <skill目录>退出码 0 = 健康，1 = 有问题（输出具体问题清单）。第 7/8/8b/8c/8d 步需人工判断，脚本不覆盖。
适合：
- ✅ 开源/发布 skill 前的验收（结构不健康谈开源是空中楼阁）
- ✅ 多轮迭代后的 skill（每轮迭代都可能产生孤儿/残留/漂移）
- ✅ 架构改造后（双模式改造、改名、换方法论——旧口径必然残留）
- ✅ 带 scripts/ 的 skill（文档与脚本割裂是体检清单上最容易漏的一项）
不适合：
- ❌ 纯知识类文档（没有执行步骤，静态检查够）
- ❌ 从未迭代过的新 skill（还没产生残留）
skill-health-audit/
├── SKILL.md # 十步体检清单（主流程）
├── references/
│ └── doc-script-split-pitfalls.md # 8b 延伸坑（脚本相对路径/config 死配置）
└── scripts/
└── audit_skill_health.py # 自动化体检（第 2/4/5 步）
这套清单从 629 本书拆解流水线的 skill 治理中沉淀——每一条都对应一次真实翻车：虚假权威声称让 agent 引用了不存在的「规定」、未闭合代码块把后半篇文档渲染成代码、孤儿 references 让写好的内容永远没人看到。逐条案例见 SKILL.md 正文。
- 体检逻辑平台无关（markdown + python）
- 示例命令面向 macOS/Linux；Windows 下 grep 换 findstr 或用 Git Bash
彬少 —— 一个什么都折腾一下的人：装系统 · 玩AI · 搭知识库 · 做设计。这套 Skill 是我自己在用的，用来检查自己写的 skill / workflow 是不是真能跑通。
微信公众号 「宝藏彬少」：折腾，是为了更好用。欢迎关注交流。
MIT