别让 Skill 变成新的文档债：从经验沉淀到行为回归

一次看起来很合理的 Skill 改动，可能会让 Agent 变得更稳定，也可能让它偏得更远。

比如我们给 Repo Knowledge Skill 加了一条规则：实现新需求前，优先查找项目里的历史相似页面。

从文本上看，这一定是正向改动。它能减少重复造轮子，让 Agent 更贴近项目规范，也更容易复用团队已有的组件、交互和调用方式。

但在真实任务里，Agent 可能因此过度复用旧页面，忽略当前设计稿和接口变化。它可能把旧页面里的交互模式迁移过来，却没有注意这次需求的数据结构已经变化；也可能因为找到了“看起来相似”的实现，就减少了对 PRD、设计稿和 API 的理解。

最后的结果是：代码风格更像项目了，需求却实现偏了。

这时候我们才会意识到：Skill 不是普通文档。它会改变 Agent 的上下文选择、工具调用和执行路径。既然它能改变行为，就必须被测试。

过去一年，很多团队都开始做一件相似的事：把经验写给 Agent 看。

有人写 Cursor Rules，有人写 AGENTS.md，有人写 Claude Skill，有人沉淀项目知识库，有人把团队规范、工具说明、研发流程、Code Review 经验改造成 Agent 可以消费的 Prompt 或操作手册。

过去很多经验只能在人脑里流转，靠口头传递，靠代码评审补充，靠老同学带新同学。现在，随着 Coding Agent、AI IDE 和各类 Agent Framework 逐渐进入真实研发流程，这些经验开始被外置成一种新的资产：写给 Agent 看的经验资产。

为了行文方便，本文借用 Skill 这个词，泛指所有写给 Agent 消费、并试图影响 Agent 行为的经验资产。它不只包括 Claude Skill，也包括 Cursor Rules、AGENTS.md、CLAUDE.md、项目知识库、团队规范、工具说明、流程约束、执行手册和验证指令。

它们的共同点是：都试图把过去散落在人、文档、代码和工具里的经验，变成 Agent 可以读取、理解和调用的上下文。

在真实研发场景里，Agent 面对的从来不是一个孤立问题。它要理解项目结构，要遵守团队规范，要知道哪些组件能用，要知道历史代码是怎么写的，要知道什么时候可以直接改代码，什么时候必须先补充上下文，什么时候必须验证，什么时候应该停下来。

这些东西如果完全塞进一次对话，成本很高，也不稳定。所以大家很自然地开始沉淀 Skill。

从这个角度看，Skill 的出现非常重要。它让 Agent 不再只是依赖模型参数里的通用知识，而是开始接入团队自己的项目经验、工程规范和执行路径。

比如在端到端研发自动化里，一个 Task Modeling Skill 可以告诉 Agent：拿到 PRD、设计稿和 API 之后，不要直接开始写代码，而是先抽取目标、范围、交互、数据、约束、验收标准和不确定项。

一个 Repo Knowledge Skill 可以告诉 Agent：不要只看当前文件，而要优先寻找项目里相似的历史实现，理解团队已有组件和调用方式。

一个 Validation Skill 可以告诉 Agent：代码生成不是结束，必须根据任务类型选择 lint、typecheck、build、单测、E2E、视觉校验、覆盖率等不同验证方式。

一个 Orchestrator Skill 可以告诉 Agent：不同复杂度任务要走不同路径，简单改动可以快速执行，复杂需求必须先拆解、建模、校验输入，再进入编码和验证。

这些东西，本质上都是经验。但 Skill 把它们从“人知道”变成了“Agent 可以消费”，这就是它的价值。

它不是发明了一种多么神秘的新技术，而是让团队经验第一次开始成为 Agent 运行链路里的显性资产。

但也正因为 Skill 变得重要，它才不能永远停留在“写得更完整”这个阶段。

经验能被 Agent 消费，只是第一步。下一步是：这些经验能不能被验证。

最开始，我们关心的是有没有 Skill。后来问题变成：Skill 写得够不够完整？

于是 Skill 开始变长，开始分层，开始有背景说明、执行步骤、注意事项、反例、工具使用方式、输入输出格式和最佳实践。

但再往前走一步，真正困难的问题会出现：Skill 写得完整，不代表它真的有效。

一个 Skill 可以把流程写得很清楚，但 Agent 可能根本没有在正确时机调用它；一个 Skill 可以列出很多注意事项，但 Agent 可能只吸收了其中一小部分；一个 Skill 可以在某类任务上表现很好，但组合进更复杂的链路之后，反而带来新的干扰。

这类问题会越来越常见。因为 Agent 系统不是一个确定性执行系统，Skill 也不是传统意义上的代码模块。它更像一种自然语言控制信号，进入模型、上下文、工具和执行环境之后，最终影响的是 Agent 的行为倾向。

这就导致 Skill 的质量很难只从文本本身判断。

有些 Skill 写得很短，但控制信号很强；有些 Skill 写得很长，但真正有用的信息很稀疏；有些 Skill 独立看没问题，但和其他 Skill 放在一起之后，优先级冲突、语义重叠、执行路径漂移，反而让 Agent 更不稳定。

这里面至少有几类典型问题。

第一类是信号稀释。Skill 写得越长，信息越多，但真正能控制 Agent 行为的信号未必变强。Agent 可能读到了大量背景说明，却没有抓住最关键的约束。

第二类是边界不清。Skill 往往用自然语言描述适用场景，但真实任务里的边界并不总是清楚。什么时候该用这个 Skill，什么时候不该用，什么时候只使用其中一部分，这些判断很难靠文本本身稳定解决。

第三类是模型差异。不同模型对长上下文、工具调用、指令层级、示例学习的吸收方式不同。一个 Skill 在某个模型上有效，不代表换一个模型后还保持同样效果。

第四类是组合冲突。单个 Skill 看起来都合理，但多个 Skill 一起进入执行链路后，可能出现重叠、冲突和优先级不明。比如一个 Skill 强调快速执行，另一个 Skill 强调先完整建模，Agent 在具体任务里到底听谁的？

第五类是缺少回归。代码改了可以跑测试，系统改了可以看监控和回归结果。但 Skill 改了之后，如果没有测试集，就只能靠体感判断它是不是更好。

这和代码不一样。代码虽然也会有复杂性，但它至少有相对明确的执行语义。一个函数改了，可以跑单测；一个模块改了，可以跑集成测试；一个系统能力变了，可以通过回归测试观察影响。

但 Skill 变更之后，很多时候我们只能看文本 diff：这里多了一段说明，那里补了一个注意事项；这里加了一个示例，那里调整了一个流程。

这些 diff 对人来说可能有意义，但它们并不能直接告诉我们：Agent 的行为到底有没有变好。

所以，如果 Skill 只是被不断编写、补充、整理，却没有进入测试和回归体系，它就仍然停留在“自然语言资产”阶段。

自然语言资产有价值，但还不是完整的工程资产。工程资产意味着它可以被验证，可以被比较，可以被回归，可以被持续迭代。它不只是“看起来更合理”，而是能在真实任务中证明自己带来了更稳定的行为和更好的结果。

所以我越来越觉得，Skill 是 Agent 工程化早期非常重要的过渡形态。它让经验第一次可以被 Agent 消费，但它还不是最终答案。真正成熟的形态，不是写更多自然语言经验包，而是让这些经验逐步变成可测试、可组合、可回归的控制资产。

换句话说，Skill 的问题，不是有没有沉淀，而是沉淀之后有没有证据。

要测试 Skill，首先要改变一个视角：我们真正要评估的，不是 Skill 文本本身，而是 Agent 被 Skill 影响之后的行为。

因为 Skill 不是函数。它不是：

更准确地说，它是一种行为控制资产。

一个 Agent 最终怎么执行任务，并不是由 Skill 单独决定的，而是由几类因素共同决定：任务本身是什么，当前上下文给了什么，底层模型如何理解和推理，系统暴露了哪些工具，以及 Skill 提供了什么经验和约束。

所以它更像这样：

这也是为什么 Skill 很难像普通函数一样被测试。因为同一个 Skill，放在不同任务、不同上下文、不同模型和不同工具环境里，可能会诱导出完全不同的执行轨迹。

这里的关键是 agent trajectory，也就是 Agent 的执行轨迹。

它看了哪些上下文？调用了哪些工具？有没有先理解任务边界？有没有找到相似历史代码？有没有扩大需求范围？有没有在关键节点做验证？验证失败后有没有收敛？最终结果是否符合预期？

这些才是 Skill 真正发挥作用的地方。

所以，Skill 的质量，不在 Skill 文件里，而在 Agent 被它影响之后的执行轨迹里。

一个 Task Modeling Skill 好不好，不应该只看它有没有列出 Task IR 字段，而要看 Agent 在真实需求里，是否真的能把目标、范围、交互、数据、约束、验收标准、不确定项拆出来，并且避免把无关内容混进执行任务。

一个 Repo Knowledge Skill 好不好，不应该只看它有没有告诉 Agent “去读项目上下文”，而要看 Agent 是否真的找到了正确的相似实现，是否复用了团队已有模式，是否避免了重新造轮子或误用旧逻辑。

一个 Validation Skill 好不好，不应该只看它有没有列出各种验证方式，而要看 Agent 是否能根据任务类型选择合适验证路径，是否能在验证失败后定位问题，是否能把验证结果反馈回执行链路。

一个 Orchestrator Skill 好不好，不应该只看它有没有定义流程，而要看它是否能让 Agent 在不同复杂度任务下选择正确路径，是否能在上下文不足时停下来，是否能在多 Agent 协作中避免遗漏。

再看一个验证相关的例子。

假设我们修改了 Validation Skill，强调生成代码后必须跑 build 和 typecheck。这当然是正向改动。但如果这次改动让 Agent 更稳定地执行了 build 和 typecheck，却开始把“工程验证通过”误认为“需求已经验收”，那么它未必真的变好。

最后可能出现一种情况：代码没有类型错误，构建也通过了，但关键交互路径、异常状态、视觉差异和回归影响都没有被证明。

这不是验证能力增强了，而是验证信号发生了偏移。

所以，测试 Skill 不能只看最终任务是否完成，更不能只看 Skill 文本是否更清楚。我们要看它到底如何改变 Agent 的执行路径。

最近 VS Code 在介绍 GitHub Copilot 的 coding harness 时《The Coding Harness Behind GitHub Copilot in VS Code》，也体现出类似方向。它真正重要的地方不是又增加了某个 Copilot 功能，而是把上下文组装、工具暴露、agent loop、工具执行和评估机制纳入同一个产品化系统；对于会影响 agent behavior 的 core tool、system prompt 或 harness 逻辑变更，也会通过 benchmark 做评估后再合入。

这个信号很重要。它说明 Agent 系统的工程化，已经不只是“选一个更强模型”，而是要把 Prompt、Tool、Loop、Context、Skill 这类影响行为的资产，都纳入评估和回归。

对企业内部的研发自动化来说，也应该是这样。

我们不能只问“模型是不是更强了”，还要问：这次 Skill 改动之后，Agent 的执行轨迹有没有变化？这种变化是变好，还是退化？有没有提升成功率？有没有降低人工介入？有没有减少重复错误？有没有让验证更充分？有没有让任务结果更稳定？

这才是 Skill 工程化真正要回答的问题。

如果接受“Skill 的质量体现在 Agent 行为里”，那下一步就很自然：Skill 需要自己的行为回归集。

我更愿意把它叫做：Skill Regression Suite，也就是 Skill 行为回归集。

它不是为了测试 Skill 文本有没有语法错误，也不是为了检查 Markdown 写得是否规范，而是为了验证：

某个 Skill 改动之后，在一组代表性任务上，Agent 的行为和结果是否变得更好，至少有没有明显退化。

这件事可以按 Skill 类型来拆。

比如 Task Modeling Skill 的测试集，应该关注需求理解和任务建模：是否能识别目标和范围，是否能拆出前端侧或客户端侧真正要执行的内容，是否能识别设计稿、API、Repo 上下文之间的不一致，是否能形成可执行的 Task IR，是否能识别不确定项，是否能避免需求范围扩大。

Repo Knowledge Skill 的测试集，应该关注上下文检索和历史模式复用：是否能找到相似页面、相似组件、相似交互，是否能识别团队已有封装，是否能遵守项目目录结构和命名规范，是否能避免误读无关代码，是否能把历史实现转化为当前任务的实现提示。

Validation Skill 的测试集，应该关注验证策略和反馈闭环：是否能根据任务类型选择验证方式，是否能区分 lint、typecheck、build、unit、E2E、visual，是否能在验证失败后定位原因，是否能把失败结果反馈给编码执行，是否能判断什么时候验证证据足够。

Orchestrator Skill 的测试集，应该关注路径选择和执行编排：是否能识别任务复杂度，是否能决定直接执行还是先建模，是否能合理拆分子任务，是否能控制子 Agent 的上下文边界，是否能在关键节点停下来做检查，是否能避免流程跳步。

这样一来，Skill 的迭代就不再只是“改文档”。它会变成一个相对明确的工程流程：

这里最关键的是 trace。

没有 trace，就只能看最终结果。看最终结果当然重要，但还不够。因为两个 Agent 最终都可能完成任务，但中间过程完全不同。一个可能路径稳定、验证充分、变更范围可控；另一个可能误打误撞、扩大范围、跳过验证，只是碰巧通过。

如果只看最终结果，我们很容易误判 Skill 的质量。

所以 Skill 测试一定要看行为 diff，而不只是文本 diff，也不只是结果 diff。

比如一次 Skill 变更之后，最终代码都能通过 build，但新的 Skill 让 Agent 少读了关键文件，跳过了设计稿对比，减少了交互验证。这种变化就不一定是好事。

反过来，如果某个 Skill 改动后，最终成功率只是略微提升，但 Agent 更稳定地识别了输入缺失，更少扩大范围，更主动执行验证，更容易收敛失败，那它可能就是一个重要进步。

这也是为什么 Skill Regression Suite 不应该只是一组任务样本，还应该包括过程证据。

一个最小的 Skill Regression Case，可以长这样：

这个例子不一定是最终格式，但它说明了一件事：Skill Regression Case 不能只保存“任务输入”和“最终结果”，还要保存期望行为、轨迹断言、结果断言和历史失败模式。

换句话说，我们不是只在测“做没做完”，而是在测 Skill 是否把 Agent 推向了更正确、更稳定、更可验证的执行轨迹。

一个比较完整的测试样本，至少应该包含几类信息：原始输入，包括 PRD、设计稿、API 和 Repo Context；期望中间表示，包括目标、范围、约束、验收标准、不确定项；期望执行路径，包括应该读取哪些上下文、应该调用哪些工具；期望验证方式，包括哪些验证必须执行，哪些可以选择执行；风险点，包括容易误改哪里、容易漏掉什么；历史失败，包括过去 Agent 在这里犯过什么错误；自动断言，包括可以用脚本判断的结果；人工评审项，包括暂时无法自动判断的标准。

这听起来会比写 Skill 更重。但这正是 Skill 从经验文档走向工程资产必须付出的成本。

没有测试集，Skill 的演进只能靠感觉。有了测试集，Skill 的演进才有可能进入回归、比较和迭代。

Skill 的迭代，不应该只看文本 diff，而应该看行为 diff。

当 Skill 越来越多之后，我们很容易形成一个 Skill Collection。

这里有一个任务建模 Skill，那里有一个仓库知识 Skill，还有一个验证 Skill、一个编排 Skill、一个设计稿解析 Skill、一个项目规范 Skill。这些 Skill 单独看都可能有用。

但真正的问题是：谁来管理它们？谁来决定什么时候调用？谁来处理它们之间的冲突？谁来评估它们的效果？谁来判断一次 Skill 变更有没有导致退化？

当每个 Skill 都需要测试集、trace、行为 diff 和发布门禁时，问题已经不只是“怎么写 Skill”了。

我们开始需要一个系统来回答更大的问题：哪些 Skill 在什么任务里被调用？它们如何组合？它们的行为如何被观察？一次变更如何判断是否退化？不同模型、不同工具、不同项目上下文下，它们的效果如何被比较？失败发生后，如何判断问题出在输入理解、任务表示、仓库上下文、执行编排、验证链路，还是 Skill 本身？

这时候，我们讨论的就不再是一组经验文档，而是一套更大的系统承载层。

如果说 VS Code 里的 Coding Harness 解决的是模型如何在 IDE 里完成编码任务，那么企业研发自动化里需要的 R&D Harness，解决的就是 Agent 如何在真实研发链路中，从输入理解、任务表示、执行编排到验证反馈，持续形成可控闭环。

它不是要替代 Skill，而是要让 Skill 进入一个可执行、可观察、可评估、可回归的系统里。在这个系统里，Skill 只是其中一类资产。除此之外，还会有 Prompt、Tool、MCP、项目知识、Task IR、执行轨迹、验证结果、Benchmark、Eval Gate。

它们共同决定 Agent 能不能在真实研发任务里稳定工作。

所以，端到端研发自动化真正要建设的，不只是更多 Skill，而是能组织 Skill 的机制，能观察 Agent 行为的 trace，能评估任务结果的 Benchmark，能测试 Skill 变更的 Regression Suite，能控制发布风险的 Eval Gate。

如果没有这些，Skill 越多，可能反而越不可控。因为我们只是沉淀了更多经验，却没有办法判断这些经验是否真的在正确影响 Agent。

这也是我现在越来越明确的一个判断：

Skill 让经验可以被 Agent 消费；测试集、trace、回归评估和 Eval Gate，才让这种经验可以被评估、被回归、被演化。

所以，这篇文章想先把问题停在这里：别让 Skill 变成新的文档债。

因为 Agentic Engineering 真正进入工程化阶段的标志，不是我们沉淀了多少经验，而是这些经验能否像工程资产一样，被验证、被比较、被回归、被持续迭代。

这也会把问题继续推向下一层：如果 Skill、Prompt、Tool、Benchmark 和验证链路都需要被统一管理，那么端到端研发自动化就不能只靠 Workflow 或 SDD 平台完成。

这个问题，我下一篇继续展开。