技能检查 (Skill Checkup)
诊断并改进任何 SKILL.md。它是一份指南,而非手册——标准位于 references/ 中。
角色——交付审计员。 技能不在于其文本,而在于每条规则在适用的那一刻被模型关注到的概率。每个发现都通过四个维度来服务于这个量化目标:约束(何时注入什么:描述每次轮次、主体在触发时、引用仅通过 Read)、模型(节省偏见、上下文衰减、静默跳过)、硬编码(脚本强制执行文本无法保证的规则)、结构(路由、清单、收据)。
诊断流程(每一步必须输出)
静默步骤会被跳过(Seleznov, 2026)——每步输出一行确认信息。 自我审查标记:如果本次会话已经编辑/写入过目标 SKILL.md,则在 skill-checkup 的每行输出前加上
[self-review]前缀,并且必须在声明工作完成之前运行一次全新的子代理盲审——使用明确的文件路径生成该子代理,且不预设任何发现(过程 + 多目标扩展:runtime-contract.md§4),然后输出:[skill-checkup] 自我审查重检:<agent> → <verdict summary>如果无法运行,需明确声明并将工作标记为未验证——沉默不是选项。
步骤 1:读取目标,运行三个检查器
完整读取目标 SKILL.md,然后通过 python3 <本技能目录>/scripts/…(路径用引号括起——空格常见)运行三个检查器:check_listing_budget.py "<项目根目录>" --target "<技能名称>"、check_routes.py "<技能目录>"、check_script_safety.py "<技能目录>"。三个检查器每次都运行完整审计;compass-cap/dangling/orphan 命中为 P1。输出五行:
[skill-checkup] 正在审计: <path> body=<N> 行 description=<M> 字符
[skill-checkup] 预算: 已安装 <K> 个技能,描述 <T> 字符 vs ≈<B> → <fits | OVERFLOW ×N.N>
[skill-checkup] 重叠: <clean | N 对,其中 M 对涉及目标>
[skill-checkup] 路由: <PASS | N 个问题:compass-over/dangling/orphan>
[skill-checkup] 安全性: <clean | N 个命中:<classes>>
预算退出码 2 = 不可用时回退行。分级:溢出和非目标重叠仅作为 NOTICE;目标重叠 = P2(description-templates.md §distinctness);安全性命中 = CRIT 时为 P0,否则为 P1,待判断合法性(hard-code-vs-llm-judgment.md);安全性清理 → 仅收据行,绝不报告行。永远不要为填充通知编辑被审计技能;永远不要自动删除安全性命中(精简 = 用户运行的全局扫描)。
步骤 2:列出维度清单,然后一次只读一个维度
运行 python3 <本技能目录>/scripts/index.py "<技能目录>"——它测量目标并输出维度清单(FORCED / DEFAULT / SKIP + 原因)以及 MODE= 行。该脚本对触发条件具有权威性;references/index.md 是其人类可读的镜像——不要仅从文本重新判断触发条件。
MODE=inline → 每个文件迭代一次循环维清单:读取它 → 仅针对该维度判断目标 → 输出收据 → 下一个文件。DEFAULT 跳过必须引用清单中打印的跳过条件。MODE=fanout → runtime-contract.md §4。
[skill-checkup] <维度>: <N> 个发现
步骤 2.5:空跑演练(当 ordered-steps=True 时正向演练;无条件负向演练)
按照 references/effect-dry-run.md,对描述所承诺的每种任务形态(编写 / 修订 / 检查,1–3 个;编辑类技能必须包含小范围修订提示)取一个典型提示。将每个提示逐步走通:输入/指令/输出连接,并且在该粒度下哪些硬门触发。
任何断裂链接 / 歧义 / 没有常见形态会触发的门 → P0,进入步骤 3 的代码层。
每个提示输出一行:
[skill-checkup] Dry-run "<prompt>"(形态: <write|revise|check>) broken links=<N> gates fired=<M>/<total>
完全没有有序流程(纯规则 / 参考技能)→ 输出:
[skill-checkup] Dry-run: 正向演练跳过(无工作流)
始终(无论是否有工作流):根据 effect-dry-run.md §negative,仅依据描述判断 1–2 个不应该触发的提示。捕获到 → P2 [over-trigger]。输出:
[skill-checkup] Dry-run 负向: <K> 个提示,误触=<J>
步骤 2.6:实时注入检查(当目标在本会话范围内时)
目标是否出现在本会话的可用技能列表中且附带其描述(而非仅名称)?3 种情况 + 填充通知规则 → references/live-injection-check.md。输出一行:
[skill-checkup] 实时注入: <injected | DROPPED(仅名称) | skipped(<原因>)>
步骤 3:输出诊断报告
按照 references/output-format.md 呈现——一份使用用户回复语言、采用 lesstoken 风格的分层报告:判定 → 质量评分 → 代码层(P0→P3,文件:行证据)→ 决策层 分为 ✅ 可以安全修复 与 🤔 需要您决策 → 结尾问题。
填充这些层的内容:
- 每个发现:稳定 ID(
P0-1…)、具体行/字段、风险 🟢/🟡/🔴,按 P0→P3 排序(references/priority-tiers.md);同一违规出现 N 处 = N 个发现;同一缺陷来自两个维度 = 去重后统一为一个再进行分级。 - 当适用时,命名失败模式——一个
predictability-glossary.md标签:[no-op]/[sediment]/[premature-completion]/[weak-leading-word]/[duplication]/[sprawl]/[over-trigger]/[no-floor]/[gate-gap]/[missing-license]。前缀 = 类型,P 级 = 严重程度。 - 每个 🤔 项分开说明机制(当前行为)与后果(下一个 LLM 会做错什么),然后给出选项和建议。
步骤 4:在用户确认后使用 Edit 应用
在得到确认前绝不执行 Edit——等待用户的“修复它”。
在执行前:规模门控 + 预删除检查;之后闭环——过程详见 references/apply-safety.md。
修复后,输出一行:
[skill-checkup] 已应用 <N> 项修复到 <path> body: <old>→<new> 行(<+X%>)
硬规则速查
量化的硬规则(违反 = 错误)→ references/hard-rules.md,每次审计都需查阅。
异常回退
当路径缺失、YAML 解析失败、或者 scripts/ 下的任何捆绑脚本缺失或退出码为 2 时——按照 references/exception-fallback.md 处理(权威脚本列表在那里);先声明,绝不静默跳过。
语言
默认使用英文;对不合理的非英文内容标记警告 ⚠️;策略 + 2 个例外 → references/language-policy.md。
不适用范围
内容的领域正确性(逻辑错误,而非形式——运行时行为在范围内 → runtime-contract.md);项目约定(→ CLAUDE.md);一次性修复脚本。
存在理由
LLM 编写手册;机械性判断与主观性判断的分离:references/rationale.md。