skills-audit

技能审查

定期审查 .agents/skills/ 下项目本地的技能集。目的是在目录变得混乱之前发现偏差——技能过多、触发条件重叠、描述与正文不再匹配，以及引用了已重命名或删除的技能。

建议频率： 每周一次，或在新增／重命名技能超过 1 个的一周之后进行。

流程

1 — 清点

建立当前清单，包括符号链接的技能。检查 package.json 脚本和 .agents/scripts/ 中是否有清点／检查辅助工具；如有，请复用，并检查其支持的选项，而不是重复编写检查逻辑。阅读每项技能的描述，并在需要调查路由、重叠或过期引用时检查正文。若没有清点辅助工具：

find -L .agents/skills -name SKILL.md | wc -l                      # total count, including symlinked skills
find -L .agents/skills -name SKILL.md -exec wc -l {} \; | sort -rn # by body length, including symlinked skills

在脑中按领域归类（数据库／状态／UI／Agent／测试／工作流／文档等）。记录上次审查后新增的技能（git log --since="1 week ago" -- .agents/skills/）。

2 — 检测重叠／冗余

对于同一领域中的每一对技能，询问：

• 描述相同？ → 可能是重复项（其中一个可能是已重命名技能的遗留项，或全局与本地技能冲突）。
• 同一任务符合多个描述？ → 检查这些技能是互补还是实际存在竞争；仅在选择含糊时明确划分界限。
• 某项技能的正文写着“另请参阅：foo”？ → 确认 foo 仍然存在，并确认交叉引用仍有意义（被引用的技能可能已纳入引用方关注的内容）。
• 技能与 AGENTS.md 中的内容重复？ → 合并到 AGENTS.md，或精简技能，只保留差异部分。

常见误报（不要合并）：

• db-migrations 与 drizzle —— 工作流不同（迁移文件与架构编写）。
• agent-runtime-hooks、agent-tracing 与 agent-signal —— Agent 系统的不同方面。
• testing 与 acceptance —— 测试类型不同。

3 — 描述与调用边界

检查描述是否清楚说明技能用途和选择边界，并与正文相符。标记会吸引无关任务的宽泛触发条件、重叠技能之间缺失的区别，以及过时的名称或引用。

不要强制要求使用 Use when 或 Triggers on 等固定短语、固定句式，或要求描述长度与正文成比例。这些是写作选择，不是运行时路由控制。将脚本的措辞启发式视为审查提示，而不是缺陷证据。

根据当前运行框架支持的元数据，核实仅显式调用设置，例如 frontmatter 中的 disable-model-invocation 或 agents/openai.yaml 中的 policy.allow_implicit_invocation。不要假设不同运行框架识别相同字段。保留预期策略；不要仅凭描述措辞推断运行时行为。

4 — 过期技能检查

对于范围狭窄的领域技能（例如 response-compliance、一次性的 CLI 工作流）：

# Confirm the referenced code surface still exists
rg -l "response-compliance|openresponses" packages/ src/            # adjust per skill
git log --since="3 months ago" -- '.agents/skills/<skill>/SKILL.md' # replace <skill>

如果相关功能已不存在，且技能已有 3 个月以上未编辑 → 标记为待归档。

4b — 持续日志新鲜度（common-mistakes.md、probe-mock-patterns.md）

这两层（.agents/skills/acceptance/references/ 通用层，.agents/acceptance/ 项目层）都会注入每轮 acceptance，因此过期条目就是过期指令。检查每条：

rg -n '^`since|holds-while' .agents/acceptance/common-mistakes.md        # every entry must carry both
rg -n 'holds-while: (?!always)' -P .agents/acceptance/common-mistakes.md # the mechanism-bound ones

• 缺少 since / holds-while → 该条目早于准入规则；要么补上这些字段，要么移至 field-notes。
• 对于每个非 always 的 holds-while，检查所指机制是否仍然存在（脚本默认值、摄取缺口、平台行为）。若已不存在 → 删除该条目（PROCESS.md Step 0 退出规则）；历史记录由 field notes 保留。
• 在通用层中提及项目脚本或产品名词的条目，所在层级不正确。
• 重复的 id（rg -o '^### [ML]-?[A-Z]?\d+' | sort | uniq -d）。

5 — 交叉引用完整性

检查实际的技能链接、命名的交接项和引用文件是否指向其所属根目录，包括符号链接目标。反引号中的代码符号或 CLI 命令不一定是技能引用。报告断链前，先解析已重命名或移动的目标；获准编辑时，修复已确认的引用。

6 — 输出报告

报告可执行的发现，提供文件引用、证据和建议的更改。区分已确认的问题和不确定的候选项。只有在有助于用户决策时，才提供清单统计或执行顺序；无需固定标题、模板或行数估算。

仅审计的请求应提供建议。用户通过 --apply 或普通语言授权修复后，应在授权范围内直接应用安全的更改，无需再次询问。删除操作需要获得涵盖目标的授权；若用户已授权，则无需再次请求。

输出规则

• 具体说明。“技能 X 与 Y 重叠”这种说法毫无用处，必须指出重叠的触发条件。
• 指出描述或正文问题时，注明行号。
• 除非调用点确实会在同一上下文中加载合并后的技能，否则不要建议合并。
• 不要建议删除近期未修改过的技能——“未使用”可能意味着“稳定”，而非“废弃”。

不要做的事

• ❌ 不要因为表格中的部分字段已过时就删除整张表或整个章节。应更新过时的字段（状态、路径、数量），并保留代码无法复现的决策信息：优先级、负责人、日期、理由。
• ❌ 未检查交叉引用以及提及旧 slug 的用户记忆条目之前，不要重命名技能目录。
• ❌ 不要仅为缩短描述或符合模板而移除有意义的选择边界。
• ❌ 不要仅因领域相同，就把 200 行以上的大型技能合并到另一项技能中——大型技能会按需选择性加载，合并会导致所有内容都被加载。
• ❌ 除非用户明确要求，否则不要建议重组为 .agents/skills/INDEX.md 或重命名为 <domain>-<skill> 前缀形式——这样做的成本大于外观整理带来的收益。