LobeHub deep-review 的 Skill Freshness 维度：让 Agent 技能库与代码演进保持同步

LobeHub（lobehub）仓库内置了一套名为 deep-review 的多维度代码评审技能，其中 skill-freshness 维度负责一件看似不起眼、实则关键的事：检测每一次 diff 是否让 .agents/skills/ 下的 Agent 技能文档“过期”了。读完本文，你将理解该维度的完整检查清单、三步检查流程、违规与豁免边界，以及它作为“advisory（仅建议、不进入验证）”维度在 deep-review 流水线中从产生、路由到最终渲染为报告 “Skill updates” 章节的完整链路。

1. 维度定位：为什么“技能新鲜度”值得单独设维

skill-freshness 维度的规则文件位于 skill-freshness.md，其开篇给出了存在理由：

Agent skills are load-bearing documentation: agents follow them literally. A diff that changes behavior a skill describes silently poisons every future agent session.

翻译过来即：技能文件是“承重文档”——Agent 会逐字遵循其中的命令、路径和约定。一个改变了技能所描述行为的 diff，会在无声中“毒化”之后每一个 Agent 会话。这个维度要做的就是让技能库与现实保持同步（in sync with reality），并识别出值得沉淀为技能的新知识。

该文件的 YAML frontmatter 声明了三个元数据（skill-freshness.md）：

字段	取值	含义
id_prefix	skill	该维度产出的 finding id 前缀，如 skill-1
verify	false	finding 为 advisory，跳过独立 verify 子代理的证伪环节
skip_when	never in deep mode (cheap)	deep 模式下永不剪枝（成本极低）

在 deep-review 的 SKILL.md 的 14 个维度总表中，skill-freshness 是仅有的两个 Verified? no 维度之一（另一个是 workflow），标记为 no (advisory)；表格注释说明：Verified? no 意味着该维度的 finding 属于“客观状态检查或建议”，跳过 verify pass，直接进入报告。

2. Quick checklist：四条快速检查项

维度文件的 Quick checklist 小节（skill-freshness.md）是 light 模式评审者实际读取的全部内容（light 模式评审提示模板明确要求“只读 Quick checklist 一节”，见 light-review-prompt.md）。四条检查项完整如下：

1. 这个 diff 是否使某个技能失效？ 具体触发因素包括：被技能按路径或名称引用的文件被重命名/移动、命令被修改、工作流被改变、技能所引用的导出（export）被删除。
2. 这个 diff 是否使 AGENTS.md / CLAUDE.md / README 设置文档中的某条陈述失效？
3. 这个 diff 是否属于“基础型工作”——后续任务将在其上构建（新子系统、新约定、新工具），却没有任何技能记录它？
4. 这个 diff 是否修复了一类反复出现的错误？ 根因知识应该沉淀进某个技能（或更新本评审技能的相关维度文件）。

这四条恰好覆盖了技能腐化的四个来源：破坏性变更（renames/removals）、根级 Agent 文档过期、知识缺口（gap）、重复踩坑（recurring mistakes）。

3. How to check：三步可执行检查流程

维度文件的 How to check 小节（skill-freshness.md）给出了可复制、可运行的具体步骤：

第 1 步：提取 diff 的“重命名与删除”清单。 从 diff 中抽取出以下五类被移动或移除的符号：文件路径、导出名（exported names）、npm scripts、CLI 命令、环境变量。

第 2 步：全局检索旧名称。 对每一个旧名称执行 ripgrep 检索：

# 对每个被重命名/删除的旧名称执行（示例）
rg "oldCommandName" .agents/skills/ AGENTS.md CLAUDE.md

规则明确：在任何被删/被改名的符号上命中，即构成一条 stale-skill finding。检索范围锁定两处——.agents/skills/ 目录（技能库本体）与仓库根级的 Agent 文档（AGENTS.md、CLAUDE.md）。

第 3 步：新子系统覆盖度检查。 对于 diff 引入的新子系统：先检查是否有既有技能的 scope 已经覆盖它；如果没有任何技能覆盖、且该子系统存在“非显然”的工作流（setup 步骤、约定、gotchas），则提出一个新技能建议，附一行 scope 描述。

4. 判定边界：什么是违规，什么不是

这是该维度文件最有价值的部分——它用两条“是”和两条“否”划出了清晰边界（skill-freshness.md）。

4.1 构成违规（advisory）的情形

• 某个技能或 Agent 文档现在陈述了错误事实——finding 必须引用确切的文件和行号（with the exact file and line quoted）。
• 明确的技能缺口（skill-worthy gap）：反复出现的错误类别，或没有“家”的基础性功能。提出建议时必须给出技能名 + 2~3 条要点内容，且要“concrete enough to act on”——不允许出现 “consider documenting this”（“考虑文档化一下”）这类空话。

4.2 明确不构成违规的情形

• 仅仅是简略或“可以改进”但不错误的技能——维度文件特别强调：这是新鲜度审查（freshness），不是质量审查（not quality review）。
• 为一次性工作（one-off work unlikely to recur）提出的推测性技能——不为不会重现的工作预建技能。

第二条与 deep-review 的核心原则 4“Calibrate to codebase and lifespan”（按代码库现状与生命周期校准，见 SKILL.md）一脉相承：不追求理想化标准，只做事实性同步。

5. Finding 的流转链路：从 advisory 到报告 “Skill updates” 章节

verify: false 不是“不认真”，而是一条完整且经过工程化保障的旁路。结合 deep-review 的编排手册可以还原其全链路：

（1）产出校验。 所有维度（包括 skill-freshness）的评审子代理都必须返回严格的 JSON（见 review-prompt.md 的返回格式约定），每条 issue 需要 id、dimension、severity、likelihood、location、summary、core_problem、fix_cost、fix_options、need_test 等字段。主代理用 validate-output.ts 做 zod schema 校验，字段缺失或 id 重复直接拒绝并重跑评审子代理。

（2）跳过验证，直达报告池。 在 Claude Code 编排手册的 Step 3 中明确规定：“Findings from verify: false dimensions go directly to reportPool”（claude-code/main.md）。也就是说 skill-freshness 的 finding 不经过独立 verify 子代理的三向裁决（confirmed / false_positive / need_more_context），直接入池。这符合其定位：引用一个已删除路径是否属实，本身就是客观可查的事实，无需对抗性证伪。

（3）Codex 环境下的分组。 在 Codex 编排手册中，skill-freshness 与 workflow、observability 被编入 process 复合维度组，由同一个子代理打包评审（codex/main.md），体现“便宜维度合并派发”的效率考量。

（4）渲染进报告。 report-template.md 的渲染规则写明：skill-freshness 的 finding 渲染在 📚 Skill updates 章节（模板第 157-159 行），独立于 P0/P1/P2 严重度分桶，且不计入任何 finding 统计。每条 finding 渲染为一行，字段映射固定：

- {location: 过期技能文件:行号 或 建议的新技能} — {summary}；建议动作: {fix_options[0]}

即 fact = summary、evidence = location（有 scenario 时附上）、suggested action = 第一条 fix_options；其 severity 字段仅为 advisory 性质，永不渲染。

6. 剪枝规则：这个维度何时跑

SKILL.md 的 Pruning table 对 skill-freshness 的剪枝条件写得最特别——它按模式区分：

模式	剪枝条件
Light	当 diff 既没有修改 Agent 指令、也没有修改任何既有技能所覆盖的行为/约定时，剪掉
Deep	永不剪枝（cheap，成本极低）

这里有一条容易被忽略的配套规则（SKILL.md）：“Docs-only” 仅指面向人类的面貌性文字。对 Agent 可执行的文件——.agents/skills/**、AGENTS.md / CLAUDE.md、prompt 模板、编排手册——在剪枝意义上一律算作代码：它们的“散文”携带控制流、契约和规则，其中的矛盾正是 logic / business-logic / reuse-architecture 维度要捕捉的对象。因此任何触及这些文件的 diff 永远不是 docs-only，skill-freshness 必然在候选集内。

7. 闭环设计：技能如何自我维护

skill-freshness 维度不只是“报警器”，它是整套技能体系自我进化的入口。SKILL.md 末尾的 “Keeping this skill sharp” 小节 说明了这个闭环：

The skill-freshness dimension and the workflow_feedback channel in the subagent return schema exist to feed observations back into these files. When a review surfaces a rule gap, an outdated rule, or a recurring team preference, update the relevant dimension file in the same PR or a follow-up — that is how calibration stays current.

即：评审中暴露的规则缺口、过期规则、团队惯例，应当在同一个 PR 或后续 PR 中回写进对应的维度文件。这与 quick checklist 第 4 条（“修复了反复出现的错误类别 → 根因知识进技能”）和第 3 条（“基础型新工作无技能承载 → 提议新技能”）互为表里：diff 驱动增量维护，审查驱动规则校准。

仓库内还存在一个互补的“存量体检”角色：skills-audit 技能（建议每周或每周技能增改名超过 1 个时执行）做的是周期性全量审计——清点所有 SKILL.md、检测重名/重叠/失效交叉引用，其第 5 步 “Stale-skill check” 同样用 rg 确认技能引用的代码面是否还存在（skills-audit/SKILL.md）。两者分工明确：

• skill-freshness（deep-review 维度）：每次 diff 触发，增量式，抓“这次变更让哪条技能陈述变假了”；
• skills-audit（独立技能）：周期性触发，存量式，抓目录级的重复、重叠与整体腐化。

从源码结构看，.agents/skills/ 目录当前已收录 40 余个技能（deep-review、zustand、db-migrations、testing、acceptance 等），技能库规模越大，“承重文档”过期造成的会话污染面就越广，这也解释了为什么该维度在 deep 模式被设计为“永不剪枝”。

8. 小结

skill-freshness 维度展示了 Agent 工程中一种值得借鉴的文档治理范式：

1. 把 Agent 技能当作代码对待：重命名/删除符号时用 rg 全量反查技能库，命中即 finding，引用确切的文件与行号；
2. 新鲜度与质量分离：只报“陈述变假”与“知识无家”，不报“写得不够好”，避免维度职责膨胀；
3. advisory 旁路降低噪音：verify: false 使建议类结论跳过对抗性验证，直接落入报告独立的 “Skill updates” 章节，不干扰缺陷分桶与合并判定；
4. 规则自维护闭环：finding 与 workflow_feedback 回写维度文件，让评审标准随项目一起演进。

对于在 monorepo 中维护大量 Agent 技能、CLAUDE.md/AGENTS.md 等 Agent 文档的团队，这套“checklist + 三步检索 + 双边界判定 + advisory 渲染”的做法可以直接照搬到自己的评审流水线中。