1. 为什么能力从来不是 Agent 的瓶颈先把结论摆在前面我见过太多团队在 Agent 项目上翻车复盘到最后几乎没有人是因为模型不够聪明而失败的。真正让 Agent 在生产环境里表现拉胯的是它不知道在什么情况下该做什么、不该做什么、做完之后怎么判断自己做对了。这三件事恰好就是资深工程师脑子里那套看不见的流程。举个特别典型的场景。你让一个刚入行的工程师去改一个线上 bug他大概率会直接打开文件、找到可疑的那一行、改掉、提交。而一个干了十年的老工程师会怎么做他会先看这个 bug 的影响面确认是不是有回归测试覆盖改完之后跑一遍相关用例再检查一下有没有别的调用方受影响最后才提交。这两者的差距不在写代码的能力而在流程。Agent 现在的情况和那个新人一模一样。你给它一个足够强的模型它能写出漂亮的代码但它不知道什么时候该停下来验证不知道哪些操作是不可逆的不知道一个改动可能牵连到哪些模块。这就是为什么把资深工程师的流程写成 skill这件事比换一个更强的模型要重要得多。所谓 skill本质上就是把一段可复用的、带判断逻辑的工作流程封装成 Agent 可以调用的能力单元。它不是简单的 prompt 模板也不是一个函数而是触发条件 执行步骤 质量门 失败回退这一整套东西。热词里反复出现的 agent skill、codex skill、skill 插件、skill 脚本说的都是同一件事让 Agent 在特定场景下按照人类专家沉淀下来的方式去干活。这篇文章我想聊的不是skill 是什么这种概念科普而是我实际把资深工程师流程拆成 skill 的过程中踩过的坑、总结出的结构、以及那些文档里不会写的判断标准。如果你正在做 agent 开发、agent 框架与编排或者只是想让自己的 AI coding agent 少犯点低级错误下面的内容应该能直接用上。2. 拆解资深工程师的隐形流程从直觉到可执行步骤2.1 专家流程的三个层次感知、判断、动作我一开始尝试写 skill 的时候犯的最大错误就是直接把步骤写下来。比如修改代码前先跑测试听起来很对但 Agent 执行起来一塌糊涂。后来我才意识到资深工程师的流程其实分三层缺一层都不行。第一层是感知他得先知道现在是什么情况。是改一个新功能还是修一个线上问题代码库有多大有没有测试这些信息决定了后面所有动作。第二层是判断基于感知到的信息决定走哪条路。有测试就跑测试没测试就先补一个最小验证。第三层才是动作具体执行。我见过的大部分失败的 skill都只写了第三层。Agent 拿到一个修改代码的 skill它不知道什么时候该用、用了之后怎么判断成功结果就是机械执行错得离谱。所以拆解流程的第一步不是记录他做了什么而是记录他在什么信号下做了什么决定。这个信号就是 skill 的触发条件。2.2 把经验翻译成条件判断的具体方法这里有个很实用的技巧找资深工程师做一次出声思考think aloud。让他一边干活一边把脑子里想的说出来。你会听到大量这样的句子这里我得小心点因为……、如果这个文件被别的地方引用了那我就不能直接改、先看看有没有现成的工具没有的话再自己写。这些因为、如果、先看看就是条件判断的原材料。我的做法是拿一张表左边记他说的话右边翻译成可执行的条件。专家原话翻译后的条件判断这里我得小心点因为这是公共模块如果目标文件被 3 个以上模块引用则进入高风险流程先看看有没有现成的执行前先检索项目内是否已有同类实现改完得跑一下相关的修改后必须执行受影响模块的测试用例这个操作没法撤销标记为不可逆操作执行前需二次确认这张表就是 skill 的骨架。你会发现翻译的过程本身就是一次知识提炼很多专家自己都没意识到自己在做这些判断写下来之后才恍然大悟。2.3 为什么步骤清单式的 skill 一定会失败我早期做过一个代码审查 skill就是把审查清单列了二十条让 Agent 逐条检查。结果呢Agent 要么漏掉一半要么在不该用某条的时候硬套。比如检查是否有硬编码密钥这条在一个纯前端展示组件里根本不需要但 Agent 还是会去查浪费大量 token。问题出在步骤清单是线性的而专家的判断是树状的。专家会根据当前情况动态选择走哪条分支而不是把所有步骤都跑一遍。所以 skill 的正确结构不是清单而是决策树——先判断场景再选择对应的子流程。这个认知转变之后我重构了所有 skill把步骤改成了分支。效果立竿见影Agent 的执行路径短了一半准确率反而上去了。3. 一个 skill 的完整结构触发、执行、质量门、回退3.1 触发条件写不好后面全白搭触发条件是 skill 的第一道关也是最容易被忽视的一关。写得太宽Agent 会在不该用的时候乱用写得太窄该用的时候又触发不了。我的经验是触发条件要同时包含正向信号和负向信号。正向信号是出现这些特征就该用负向信号是出现这些特征就绝对不能用。举个例子一个重构 skill的触发条件正向信号代码存在重复逻辑、函数超过 50 行、有明确的坏味道注释负向信号文件正在被其他分支修改、处于发布冻结期、没有测试覆盖负向信号特别重要。很多事故都是因为 Agent 在一个不该动的时刻动了代码。加上负向信号之后Agent 会主动拒绝执行这比执行错了再回滚要安全得多。提示触发条件里的每一个信号都应该是可以被程序化检测的。如果一条信号需要人来判断那它就不适合放在触发条件里应该放到质量门里。3.2 执行步骤要带意图说明而不是纯命令Agent 执行 skill 的时候如果只给它命令它会机械照做如果给它意图它能在遇到意外时做出合理调整。这是我在实际项目里验证过很多次的经验。对比一下两种写法# 纯命令式 1. 读取目标文件 2. 找到目标函数 3. 替换实现 4. 保存文件 # 带意图式 1. 读取目标文件意图确认当前实现避免基于过时信息修改 2. 定位目标函数意图确认修改范围如果函数被多处调用需标记 3. 替换实现意图保持接口不变只改内部逻辑 4. 保存并验证意图确认修改后语法正确、测试通过带意图的写法Agent 在第二步发现这个函数被 8 个地方调用时会主动停下来提示风险而不是闷头改完。这就是把专家的谨慎注入了 skill。3.3 质量门让 Agent 自己判断我做对了吗质量门是我认为整个 skill 结构里最有价值的部分也是最难写的部分。它的作用是在 Agent 声称完成之前强制它做一次自我验证。质量门分两类。一类是硬门必须通过才能继续比如测试必须全绿、语法检查必须通过。另一类是软门不通过会警告但不阻断比如代码复杂度上升了、新增了未使用的变量。硬门的判断标准要极其明确最好是二值的。我见过有人写代码质量要好这种质量门Agent 根本没法判断。正确的写法是圈复杂度不超过 10、没有新增的 lint 错误这种可量化的。软门则用来捕捉那些不致命但值得注意的情况。它的价值在于给人类审查者提供线索而不是阻断流程。质量门类型判断方式不通过时的行为硬门-测试运行测试套件检查退出码阻断回退到修改前状态硬门-语法运行编译器或 linter阻断提示具体错误位置软门-复杂度计算圈复杂度变化警告记录到执行日志软门-影响面统计受影响模块数量警告建议人工复核3.4 回退机制失败不是终点而是分支回退机制经常被忽略但它决定了 skill 在生产环境里能不能用。一个没有回退的 skill一旦失败就会留下烂摊子。回退的设计原则是每一步都要有对应的撤销动作。改文件之前先备份执行命令之前先记录状态调用外部接口之前先确认幂等性。这些看起来是常识但在 skill 里必须显式写出来因为 Agent 不会想当然地去做。更进一步回退本身也可以是一个分支。比如测试失败之后不是简单回滚而是进入诊断分支分析失败原因如果是环境问题就重试如果是代码问题就回退并报告。这种失败即分支的设计能让 skill 在复杂场景下表现得像一个有经验的工程师而不是一个脆弱的脚本。4. 把流程写成 skill 时最容易踩的五个坑4.1 坑一把 skill 写成了万能工具我见过最典型的失败案例是一个团队做了一个代码修改 skill试图覆盖所有代码修改场景。结果这个 skill 臃肿到没人敢用Agent 调用它的时候经常走错分支。正确的做法是按场景拆分。修 bug 是一个 skill加功能是一个 skill重构是一个 skill每个 skill 只处理一类场景。热词里提到的测试 skill、看图技能 skill、GIS 空间分析 skill都是这种按场景拆分的思路。拆分的粒度怎么定我的标准是如果一个 skill 的触发条件需要写超过 5 条或者执行步骤超过 10 步就该考虑拆了。4.2 坑二忽略了上下文预算Agent 的上下文是有限的skill 写得越长留给实际任务的上下文就越少。我早期写的 skill 动辄两三千字结果 Agent 光读 skill 就耗掉大半预算真正干活的时候反而没空间了。后来我把 skill 压缩到 500 字以内把详细的参考文档放到外部需要的时候再检索。这个思路和渐进式披露是一个道理核心流程精简细节按需加载。注意skill 的长度和它的可靠性不成正比。我实测下来500 字以内的 skill 执行成功率反而更高因为 Agent 不容易在长文本里迷失重点。4.3 坑三质量门写成了走过场有些团队的质量门形同虚设比如检查代码是否符合规范Agent 随便看一眼就说符合。这种质量门不但没用还会给人类审查者虚假的安全感。质量门必须可验证、可复现。判断标准要具体到运行哪个命令、看哪个输出、什么值算通过。如果一条质量门没法用程序验证那它就不该存在。4.4 坑四没有考虑skill 之间的协作实际工作里一个任务往往需要多个 skill 配合。比如修复一个 bug可能涉及定位 skill、修改 skill、测试 skill、提交 skill。如果这些 skill 各自为政Agent 在它们之间切换的时候就会丢失上下文。我的做法是给每个 skill 定义清晰的输入输出契约。上一个 skill 的输出就是下一个 skill 的输入。这样即使 skill 是独立开发的也能串起来用。4.5 坑五写完就不管了skill 不是写完就完事的它需要持续迭代。我建议给每个 skill 加一个执行日志记录每次调用的场景、结果、失败原因。定期复盘这些日志你会发现很多设计时没想到的边界情况。我自己的习惯是每周看一次 skill 的执行日志把高频失败场景提炼出来要么补充到触发条件里要么新增一个分支。这个过程持续几个月之后skill 的可靠性会有质的提升。5. 从能跑到可信skill 的验证与迭代5.1 怎么判断一个 skill 是真的可用能跑通和可信是两回事。一个 skill 在 demo 里跑通很容易但在生产环境里稳定可用是另一回事。我判断一个 skill 是否可信看三个指标。第一个是触发准确率该触发的时候触发了吗不该触发的时候有没有误触发这个指标需要收集大量真实场景的调用记录才能算出来。第二个是执行成功率触发之后有多少次是完整走完流程并达到质量门的第三个是回退率失败之后回退机制有没有正确生效这三个指标里我最看重触发准确率。因为触发错了后面全错。执行失败还可以重试触发错误往往是灾难性的。5.2 用真实任务做回归测试skill 的测试不能只用构造的样例必须用真实任务。我的做法是维护一个回归任务集里面是过去真实发生过的任务每个任务都有明确的预期结果。每次修改 skill 之后跑一遍这个任务集看通过率有没有下降。这个任务集不需要很大20 到 30 个就够但必须覆盖各种边界情况正常场景、异常场景、高风险场景、多 skill 协作场景。我见过有团队用 5 个任务做回归结果 skill 一上线就出问题因为那 5 个任务太干净了。5.3 迭代的节奏小步快跑还是大版本我的经验是小步快跑。每次只改一个点改完立刻跑回归通过了再改下一个。大版本更新看起来很爽但一旦出问题很难定位是哪个改动导致的。具体节奏上我会把 skill 的改动分成三类修 bug立即改、优化触发条件攒几个一起改、重构结构谨慎需要完整回归。这三类的节奏不一样混在一起改容易乱。5.4 让 skill 自己长出新的分支这是我觉得最有意思的一点。当 skill 运行足够久之后执行日志里会积累大量意外情况。这些意外情况其实就是新的分支。比如一个代码修改 skill运行三个月后日志里出现了十几次目标文件是自动生成的这种情况。这时候就可以新增一个分支检测到文件头有自动生成标记时拒绝修改并提示用户改源文件。这种从日志里长出来的分支比设计时拍脑袋想出来的分支要靠谱得多因为它们来自真实场景。6. 几个可以直接抄的 skill 结构模板6.1 高风险操作 skill 的骨架高风险操作指的是那些不可逆、影响面大的操作比如删除文件、修改公共模块、执行数据库变更。这类 skill 的核心是多重确认。触发条件 正向操作目标被标记为高风险 / 影响面超过阈值 负向处于冻结期 / 无备份 执行步骤 1. 评估影响面意图确认风险等级 2. 生成操作预览意图让人类看到将要发生什么 3. 请求确认意图不可逆操作必须人工介入 4. 执行操作意图在确认后执行 5. 验证结果意图确认操作达到预期 质量门 硬门操作前后状态可对比 硬门有完整的操作日志 软门影响面在预期范围内 回退 执行前备份失败时自动恢复6.2 探索型任务 skill 的骨架探索型任务指的是那些目标明确但路径不确定的任务比如找出这个 bug 的原因、调研某个方案的可行性。这类 skill 的核心是控制搜索范围。触发条件 正向任务描述包含找出、调研、分析等词 负向已有明确解决方案 执行步骤 1. 明确搜索边界意图避免无限扩散 2. 收集候选信息意图广度优先 3. 逐个验证意图深度优先 4. 汇总发现意图形成可读结论 质量门 硬门结论有证据支撑 软门搜索范围未超出初始边界 回退 无探索型任务失败不产生副作用6.3 多 skill 协作时的编排要点多 skill 协作最容易出的问题是上下文丢失。上一个 skill 的结论下一个 skill 不知道。解决办法是定义一个共享的任务上下文所有 skill 都从里面读、往里面写。这个上下文不需要很复杂一个结构化的 JSON 就够。关键是每个 skill 都要明确声明我从上下文里读什么我往上下文里写什么。这样即使 skill 是不同人开发的也能拼在一起用。字段写入者读取者任务目标编排器所有 skill当前状态每个 skill下一个 skill已执行操作每个 skill回退逻辑质量门结果每个 skill编排器7. 我个人的一些实操体会做了一段时间之后我最大的体会是skill 的价值不在于让 Agent 更聪明而在于让 Agent 更守规矩。模型的能力已经足够强了缺的是在正确的时候做正确的事的纪律性。而纪律性恰恰是资深工程师和新人最大的差距。另一个体会是写 skill 的过程其实是在逼团队把隐性知识显性化。很多流程老工程师自己都说不清楚写 skill 的时候被迫想明白。这个过程本身就有价值哪怕最后 skill 没做出来团队对流程的理解也上了一个台阶。最后分享一个小技巧如果你不知道从哪个流程开始写 skill就去找团队里最常被问的问题。新人反复问的那些问题往往就是最值得沉淀的流程。把它们写成 skill既解决了新人的困惑也让 Agent 有了可遵循的路径。这比从零设计一个完美流程要实际得多。