通用技能深度审计

它解决什么问题

给 agent 写 skill，最难的不是“跑通一次”，而是判断它在别的机器、别的 agent、别的工作目录下还能不能跑。手工 review 的问题很具体：

• 看了目录结构，忘了检查脚本里的路径是否越界；
• 改完 SKILL.md 的措辞，没意识到 13 个步骤缺了收敛条件，反复跑会重复扣费；
• 在不同 agent 之间迁移时，才发现依赖的 skill 根本没安装，或者 frontmatter 里的 name 字段写错了导致 hub 发布状态无法确认。

skill-deep-audit 做的事情是把这套检查变成可重复执行的静态审计，用同一套规则产生同样的扣分结果，而不是靠审计者的临场判断。

核心能力与工作流程

只读、不执行被测 skill。 审计过程中不会触发任何被测 skill 的写操作，也不会修改被测 skill 的文件。唯一的例外是显式授权后的 --fix，而且必须先做完整目录备份，修复完成也不会自动复检。

工作流程分八个步骤，关键节点如下：

1. 确认检查深度。 必须在开始前让用户选 L1 static 还是 L2 dryRun，然后等待用户明确答复，不能默认跳过。
2. 定位 skill 目录。 按名称查找或直接使用用户提供的路径。找不到就停止，不猜测、不兜底。
3. 静态扫描 D1–D6。 按 references/check-rules.md 定义的顺序执行，命中判定只依赖规则文件里的 grep pattern、关键词表和数值阈值，不允许审计者凭主观印象下结论。规则标题含 L1 的在两个深度都跑，含 L2 dryRun 的只在 L2 跑，L1 下标记为跳过。
4. Hub 存在性检查（仅 L2）。 需要 skill-hub 查询工具，工具缺失时降级为 WARN 而不是中断。
5. D7 依赖与体量分析。 检查依赖 skill 是否本地存在、是否只在 hub 上未安装、是否完全找不到；脚本数 ≥ 10 或代码 ≥ 5000 行时给出拆分建议。
6. 汇总计分。 总分 120 分，七个维度按 D1–D7 划分权重。

计分模型有两个容易误解的地方。 第一，任何 ERR 命中都直接判定 FAIL，不管总分多少——分数只是给修复排序用的，不是质量的唯一判据。第二，四个“0 分 ERR”（D3-E4、D3-E5、D3-E6、D4-E6）不扣任何分值，但命中同样导致 FAIL。这四个规则针对的是静默失败，扣分没有意义，阻断才是正确的处理方式。D3-E5 路径越界判定由内置的 scripts/check_path_boundary.py 完成，只依赖 python3 >= 3.8 标准库，不需要 pip 安装，完全离线运行。

跳过项的处理规则也值得留意。 跳过项不计入实际满分，但及格线不变，L1 实际满分 117、L2 为 120，及格线统一是 90 分且零 ERR。

适用边界与注意点

它是静态检查器，不是测试运行器。 L2 dryRun 做的是可达性检查（比如脚本是否存在、依赖 skill 是否安装），不会真的执行业务逻辑。运行时错误只能靠实际调用暴露。

扩展名覆盖是个已知盲区。 文件列表收集如果只匹配 *.js，会漏掉 .cjs、.mjs、.ts；Python 脚本用 subprocess 调用同名 .cjs 时，审计器会误报“被调用的脚本不存在”。规则文件里已经明确要求所有扩展名扫描使用完整集合，但如果你自定义了检查脚本，需要自己留意这点。

软依赖缺失只会降级，不会失败。 skill-hub 查询工具缺失时，Hub 相关检查被跳过并标记为 WARN。这意味着在没有安装 clawhub 等工具的环境里，审计报告的 D7 部分完整度会降低——报告里会出现“cannot verify”条目，需要人工补查。

审计报告本身要排除在被测包之外。 生成的 AUDIT-*.md 如果留在 skill 目录里，会被 D4-E5 当成未清理的冗余文件检测到。D4-E5 扫描时会显式排除这些文件，但打包发布前仍然需要手动清理。

--fix 的能力边界被刻意收紧。 5.1 类的纯文本、配置、文档修改可以批量应用，5.2 类涉及业务逻辑或脚本代码的修改必须逐项征得用户确认。删除文件不在自动修复范围内，即使文件看起来冗余也需要单独询问。修复完成后不会自动重新审计，而是提示用户手动触发——审计和修复保持解耦，方便回滚。

这套设计整体上是保守的：宁可少修，也不误改。对审计工具来说这是合理的取舍，但意味着你仍然需要自己判断报告中的 WARN 项是否值得动手。