Agent Skills Audit — Security skill for Claude Code

🔍 Agent 技能库审计（skill-audit）

LLM Agent 技能库的全库审计 SOP：9 项检查 + 线性流程 + 决策表，全模型检测，不用脚本、不存快照。

**作者：** [w-weixiao](https://github.com/w-weixiao) · **协议：** MIT

---

🎯 一句话概括：它能干什么

帮你**快速扫完整个技能库**，命中即修、规模不失控——把 25 个技能全库治理压成"跑一遍、出一张决策表、收工"。

不是帮你写技能，而是套**可重复执行的审计流程**——管"全库哪些技能该修 / 该删 / 该留、为什么这么判、哪些得你拍板"。

🔥 碰到的痛点

技能库长到一定规模后，几乎人人都会撞上这几堵墙：

• 🔗 死链 / 死引用：删了一个技能，另一个技能里的引用没跟着修，YAML 解析直接挂。
• 📐 触发词太窄 / 纯动作无场景：换个说法就路由不到，技能形同虚设。
• 🧪 两个技能功能重叠 >70%：一个工具两个入口，改一处漏一处。
• ⏰ 写死的路径 / 端口过期：工具改名 / 接口变更，文档里还留着旧值。
• 🧯 否定禁令堆成屎山：满屏"禁止 / 不要 / 别"，模型读到的是禁令不是做法。
• 📦 主文件膨胀：内联大代码 / 大参考，该拆 references 没拆。

逐项人工查容易漏、容易反复——这正是"全模型检测、不用脚本、不存快照"要解决的。

❄️ 冷跑在本审计里的角色：只读不重跑

本审计里唯一和"冷跑"打交道的地方，是**读各技能 frontmatter 的 `cold_run` 字段判断冷跑状态，不代跑**。先把冷跑本身说清楚，再讲审计怎么用它。

**冷跑原理（怎么跑）**：起一个**零上下文子代理**，只喂技能文档本身（不带背景、不带对话历史、不带编写者脑子里的理解），让它照文档执行一次典型任务，回报走了哪条分支、哪句文档不确定。你把回报和编写意图逐条对读——读歧义、跳步、自创规则、漏读导航行，任一命中即"偏差"。有偏差就回正文把该处写成显式判断逻辑，再冷跑一次；**连续两次零偏差才算收工**，中间任一次偏差计数归零。

**冷跑作用（为什么需要）**：验证"模型只看文档会不会跑偏"——编写者读文档时带着自己的上下文，零上下文模型没有，冷跑补的正是这个差；同时留下"哪版验过"的证据，回填进 frontmatter 的 `cold_run` 字段（版本+日期+方式）。

**审计怎么用（只读）**：扫每个技能的 `cold_run` 字段，取出其中的 v 号（去掉 v 前缀）== 当前 `version` = 该版已冷跑（跳过）；缺 `cold_run`、缺 `version`、或 v 号对不上 = 该版未冷跑/已失效，标进报告"**需补冷跑**"独立节——审计只标不代跑，交编写侧（[skill-authoring-guide](https://github.com/w-weixiao/agent-skills)）走 TDD 冷跑。这是审计唯一和冷跑打交道的地方。

一句话：冷跑在编写侧"跑出来"，在审计侧"读状态"——审计不重跑，只判哪版验过、哪些需补。

🌟 用了以后的效果（一般结论）

按本 SOP 跑完之后：

• ✅ 一次扫描覆盖全库（25 个活动技能级别），命中即修并进报告，规模不失控。
• ✅ 每个判定都带"依据命中项 + 排除法"——不拍脑袋，不"我觉得该删"。
• ✅ 只有"无法自动解决"和"影响功能整体"两类才停下来等你拍板，其余自动放行。
• ✅ 冷跑状态只读不重跑——读各技能 frontmatter 的 cold_run 字段判"哪版已验 / 需补跑"，不代跑。
• ✅ 审计管存量、编写管增量，分工不重叠，不会跟编写规范打架。

📊 我们实测的效果（以本项目技能库自身数据为判断标准）

以下全部来自本仓库技能库的真实运行记录，不是营销话术。

指标	数据
📌 当前版本	v2.6.0
❄️ 冷跑验收	两轮零偏差：新增"备份""部署"两场景各 12 行处置全对；红线保留 / 否定转写 / 已定死 / 标待核实 / 补锐利 五类全部判死、无翻转
🧭 全库治理	25 个活动技能全库扫描：命中收紧 9 个（触发词过窄 / 纯动作无场景 / 超体量）、保留 16 个；YAML 全部解析通过
🧯 防屎山硬上限	主文件 ≤ 80 行（日常标准），超限=打回先瘦身再审计别人；不存"活动技能清单"快照（现算，快照必烂）