做 Agent 项目做到第四年我越来越确信一句话Agent 缺的从来不是能力。长上下文、function calling、多智能体协作模型厂商早就帮你卷完了你真正要解决的是让 Agent 在一个任务里表现得像一位有章法的工程师而不是一个什么都懂一点的实习生。而这件事的抓手就是把资深工程师的流程写成 skill。同一套模型底座给不同的团队用产出质量能差出好几倍。差距不在模型在有人把“先做什么、后做什么、什么时候停下来问人”写成了机器能照着执行的操作规程有人没有。这篇文章不是讲怎么调 prompt 的。prompt 是让 Agent“说对一句话”skill 是让 Agent“做对一件事”。我会从流程拆解、骨架设计、代码审查实战、工程化管理讲到避坑经验适合所有正在做 Agent 应用落地、或者想把团队里老工程师经验沉淀成资产的人参考。1. 先破题Agent 卡住的瓶颈到底在哪1.1 同一个 Agent为什么换个人用效果差一倍先说一个很常见的现象。同一个 Agent接了同一个大模型A 同事拿来用能稳定产出可以直接合入的代码评审意见B 同事拿来用得到的全是“建议增加异常处理”“考虑性能优化”这种正确的废话。很多人第一反应是 B 不会写 prompt于是去调提示词、调温度参数折腾半天没什么起色。问题的根子不在 prompt在流程。资深工程师拿到一个代码审查任务脑子里跑的是一套完整动作先看这次变更要解决什么问题再读 diff 涉及的核心逻辑然后按数据流过一遍边界条件接着查性能和安全风险最后看测试覆盖没覆盖到关键分支。每一步都有明确的检查项和判断标准甚至包括“发现阻断性问题就先停下来不要把后续步骤做完再汇总”。而裸 Agent 拿到任务时本质上是把“给我审查这段代码”当成一次性的问答任务处理它能调用模型的知识但没有流程约束自然想到哪说到哪。这就是差距的来源。模型的能力是底座但底座之上还需要一层“流程操作系统”。没有这层系统Agent 的能力再强输出也是散的。1.2 skill 不是提示词也不是插件把“流程”落到 Agent 上业界目前公认的载体就是 skill。但这个词已经被用滥了很多人把一段写得比较长的 system prompt 也叫 skill把封装了一个外部 API 的工具也叫 skill。我的理解是提示词描述的是任务skill 描述的是完成任务的流程。插件/工具解决的是“Agent 能干什么”skill 解决的是“Agent 应该怎么干”。一个 skill 通常包含多轮提示、工具调用编排、状态判断、验收标准和兜底策略。打个比方。提示词是面试现场让候选人临场发挥skill 是给这位候选人一本操作手册加一套检查表加一张决策树。两者都能让 Agent 开口但只有后者能让 Agent 稳定地产出符合资深水准的结果。那为什么不直接用 workflow 之类的可视化编排工具我也用过卡在两个地方一是可视化编排对复杂分支和动态判断的支持弱一旦流程里出现“根据上一步结果决定下一步跳转”的逻辑图画起来非常痛苦二是流程描述和提示词、工具定义分离改一处要动好几个地方。skill 的核心思路是让流程描述、决策逻辑和工具定义集中在一个包里面版本化和复用都更顺手。所以后面我讲的 skill你可以理解成“一份带结构化流程定义的提示词包”而不是狭义上的某个固定工具格式。2. 把资深工程师的“手上流程”拆成可复制清单2.1 先给自己的流程做一次能力审计写 skill 之前最忌讳的事是拍脑袋凭印象觉得某个流程是“先 A 再 B 再 C”直接开写。真到落地的时候你会发现脑子里想的流程和手上实际跑的流程差得很远。资深工程师的很多动作是自动化的他自己都未必能清晰说出来。我的做法是做一个“能力审计”选一个过去三个月里高频执行、且结果比较稳定的任务打开录音或者边做边记把它完整跑一遍。不用刻意改变节奏就按平时的习惯来但要记录三样东西动作序列、决策点、兜底策略。举个例子。我给自己记录的“线上问题排查”流程跑完一遍之后整理出来是第一步不是看代码是先确认影响范围哪些用户、哪些接口、什么时候开始。第二步看监控大盘而不是直接翻日志。第三步根据监控定位到具体服务实例再查该实例的日志。第四步才是看代码定位可疑变更。第五步决定是回滚还是热修复。这五个步骤里有两个关键决策点什么情况下直接回滚、什么情况下可以继续排查再修复。还有一个兜底策略如果 15 分钟定位不到根因立刻通知相关团队一起介入。这些内容单独问任何一个资深工程师都说得出但它从来不会被写进文档里。2.2 选对第一个 skill 比会写更重要很多人一上来就想把团队里所有流程都做成 skill这是一个很大很大的坑。流程的梳理和验证非常耗时做十个半成品不如做一个能用的。我选第一个试点 skill 的时候会拿五个标准卡一遍判断维度具体标准说明频率每周至少执行 2 次以上频率越高打磨和验证的机会越多稳定性流程步骤基本固定如果每次执行路径都差很多说明流程尚未成型输入输出有明确的输入边界和结果形态比如“输入 PR 链接输出审查报告”可验收结果能被判断好坏没有验收标准的 skill 是没法迭代的存量经验团队里已有成熟的执行经验没有存量经验的流程AI 再强也编不出来拿这五个标准去筛最适合做第一个 skill 的往往是代码审查、故障复盘、技术方案评审这几类。它们流程稳定、结果可见、经验存量丰富。选对第一个后面才有信心继续做。3. skill 的骨架设计输入、状态、动作、验收3.1 四要素模型像菜谱但比菜谱严格我自己总结的 skill 骨架是四个要素输入协议、状态节点、动作定义、验收标准。任何 skill 都围绕这四个东西搭缺一个都会在工作时露馅。输入协议规定“什么任务能用这个 skill”任务的目标是什么、输入数据长什么样、有哪些已知限制、哪些信息缺失时需要向用户确认。状态节点就是流程的步骤本身每一步要写清楚前置条件、要做的事、产出物是什么以及下一步跳转到哪里。动作定义则包括调用哪些工具、以什么格式解析工具返回结果、什么情况下需要重新读取数据。验收标准是最后一步也是被忽略得最多的一步它定义“什么质量的产出才算完成”。如果用做菜来类比普通提示词是告诉 Agent“这道菜要好吃”而 skill 是给了它一份菜谱但是一份比普通菜谱更严格的菜谱——不仅写了食材还写了“什么时候转小火”“怎么判断肉熟没熟”“如果锅烧干了怎么处理”。严格的菜谱才能保证不同的人做出来口味一致skill 也一样。3.2 上下文窗口不是用来装整个流程说明的写 skill 容易犯的另一个毛病是把所有细节都塞进上下文里。很多人设计 skill 的时候把几十页流程文档、全部代码仓库结构、所有历史案例一股脑丢给 Agent以为信息越全输出越准。实际效果是灾难性的。模型在长上下文里的注意力是会被稀释的。核心指令淹没在大量背景资料里Agent 执行起来经常优先级错乱。我的经验是上下文分三层第一层是 skill 的定义文件只放流程骨架和规则控制在 2000 字以内。这一层是 Agent 每次执行都完整读取的必须精炼。第二层是当前任务的状态数据比如“本次代码审查的对象是 PR #123变更涉及 5 个文件”“当前已进行到性能检查步骤”。这层信息由调用方在执行过程中动态写入。第三层才是参考资料比如团队规范文档、历史案例、代码仓库结构。这一层不进主上下文由 Agent 在需要时通过检索按需拉取。这样设计之后Agent 每一步都能轻装上阵只在具体环节加载对应资料。上下文不是越大越好是越聚焦越好。3.3 显式告诉 Agent“你不知道你不知道”资深工程师和普通执行者的最大区别是知道自己什么时候该停下来。这个特质必须写进 skill。我在每一个 skill 里都会增加一个“兜底与止损”章节明确写清楚三件事第一什么情况下停止执行流程比如输入数据与预期结构不一致、关键依赖信息缺失第二什么情况下需要向用户确认而不是自作主张比如存在两个可行方案且无法基于现有信息判断优先级第三什么情况下直接给保守答案比如无法确认安全性就在结果里标红提示而不是强行给一个结论。听起来很基础但这一步能拦住 80% 的 Agent 翻车。没有兜底策略的 skill等于让一个没有经验的工程师在无人复核的情况下直接生产代码风险极高。4. 实操案例把“代码审查流程”写成 skill4.1 先定义输入输出再写过程理论讲再多不如一个完整案例。我拿自己做过的“代码审查 skill”拆开讲讲。第一步是定义输入协议。我要求调用方必须提供三个东西PR 的链接或者完整 diff、变更说明这次改动的业务目标和设计思路、目标分支信息。如果缺变更说明skill 会先停下来问用户要而不是自己猜。输出协议则规定问题清单按严重程度分级每条问题必须包含文件路径、行号级别定位、问题描述、触发场景、修改建议五个要素并且在最前面给出一个总体结论注明是否建议合入。这些输出规则看起来很死板但只有定得够死结果才可比较。Reviewer 人工审查时可能凭经验给出灵活的反馈但 skill 的产出必须稳定可预期否则用户不敢依赖它。4.2 把资深工程师的检查清单结构化接下来是核心部分把资深工程师的审查顺序写成状态节点。我梳理出的七个节点是意图确认、功能正确性、边界条件、性能隐患、安全风险、可维护性、测试完备性。意图确认是第一关先看变更说明和 diff 是否匹配防止“说一套做一套”。功能正确性按数据流走一遍输入怎么进来、中间怎么处理、输出怎么出去哪个环节逻辑可能出错。边界条件检查空值、超长输入、并发、重复提交这些场景。性能隐患重点看循环内的查询和调用、大对象复制、锁粒度。安全风险关注注入、越权、敏感信息泄露和加密存储。可维护性看命名、函数长度、重复代码和模块耦合。最后测试完备性检查有没有覆盖关键分支和异常路径。这七个节点不是简单并列关系。我在这份 skill 里做了一个很关键的设计功能正确性检查如果发现阻断性问题流程直接跳到“产出审查报告”跳过后续的性能和可维护性检查。理由很实际一个逻辑都是错的 PR不值得继续花时间看风格问题。先报告阻断问题让开发者改完了下一版再审效率最高。这就是状态节点的跳转逻辑也是 skill 和普通提示词的本质区别。4.3 状态跳转和工具调用的落地写法流程设计好了还要把它写成 Agent 能执行的结构。我习惯在 skill 文件里用伪代码定义状态机比如STATE.意图确认: 检查: diff 内容与变更说明是否一致 若不一致 - 输出审查结果标记[阻断] 若一致 - 进入 STATE.功能正确性 STATE.功能正确性: 动作: 按数据流逐段分析核心逻辑 检查: 是否存在逻辑错误/空指针/错误处理缺失 若存在阻断问题 - 输出审查结果跳过后续节点 若存在非阻断问题 - 记录清单进入 STATE.边界条件 ...每个状态节点里还绑定了工具调用定义。比如“边界条件”这个节点我会要求 Agent 先调用代码搜索工具把相关函数的调用方拉出来看一遍确认外部传入的数据形态而不只是对着 diff 干想。这很重要很多 bug 不在被改的函数内部在调用方传参时已经埋下了隐患。工具调用不是可选项是特定节点的强制执行项这样 Agent 才不会偷懒“凭记忆判断”。4.4 验收标准是防偷懒的最后一道闸最后是验收标准。我发现如果不对输出做强制约束Agent 给的结果很容易滑向正确的废话。所以我给这份 skill 的验收标准写得很具体所有风险结论都必须在 diff 中找到对应代码片段作为证据每个建议必须指出具体的修改位置和改法严重级别为高的条目必须有可复现的触发路径描述如果 Agent 认为代码没有风险必须在报告里明确写出“根据 XX 逻辑判断未发现 XX 问题”而不允许只写一句“整体质量良好”。设计这个验收标准的原因很简单AI 最大的风险不是犯错而是让用户无法判断它错没错。当输出结构固定且有据可查错误就更容易被发现和修正。这也是我建议所有写 skill 的人都要做的一件事定义一个“不合格的产出长什么样”比定义“合格的产出长什么样”更能提升结果质量。5. 写 skill 的工程化姿势版本管理、测试、迭代5.1 skill 本身也要做代码评审和版本管理skill 写到第三步已经不只是“一段提示词”了它是一个需要长期迭代的软件资产。我在团队里推了一套很简单的管理方式每个 skill 是一个目录目录里包含定义文件、示例输入输出、测试用例、变更记录。任何改动都按代码评审的流程走不允许有人偷偷在线上热更新 skill。这套流程带来的好处非常直接。第一skill 的改动可追溯出了问题能快速定位是哪次改动引入的。第二强制评审意味着至少有一个其他人理解这个 skill 的逻辑不至于它变成某个人脑子里的黑盒。第三示例输入输出作为静态文件保存下来天然形成了回归测试的原始语料。5.2 给 skill 配一组“金标准测试用例”skill 改到后面最怕的是改 A 坏了 B。所以我在每个 skill 目录下维护一批“金标准用例”也就是历史上实际发生过的、被资深工程师验证过处理得不错的场景。做法很简单每修一个线上问题就把当时的输入数据和期望输出整理成一个用例每产生一个有代表性的典型场景也收录进来。测试时拿这些用例跑一遍 skill看 Agent 的输出是否还能满足验收标准。如果某次改动导致之前的典型场景输出质量下降就知道这次的改动有问题需要调整。这个做法借鉴了软件工程里的回归测试思路。skill 的本质是逻辑代码测试保障和代码一样重要。没有金标准用例的 skill改一次崩一次最终会让大家不敢再动它。5.3 观察人机协作的摩擦点反推 skill 问题除了正式的测试我还有一个习惯每次用户在使用带 skill 的 Agent 产出结果后我发现最终修改的次数往往能暴露出 skill 的问题。如果用户在某个固定节点反复修改输出我会重点检查那个节点。修改一次可能是人的偏好不同反复修改就说明 skill 在这一步的设计和真实需求不匹配。有一个案例很典型我写的代码审查 skill 里有一个节点是“项目结构检查”结果发现用户每次都会删掉这条意见的前半部分。后来回访才发现他们的项目里那部分结构是历史遗留问题所有人都知道不用改skill 每次提出来反而制造噪音。移除这个节点之后用户对输出的满意度立刻上去了。人机协作的摩擦点就是 skill 的改进点这个规律我用了很久。6. 常见问题与避坑实录6.1 高频问题排查速查表我把实际使用中频率最高的一批问题做了个速查表写 skill 卡壳的时候可以参考。现象可能原因解决方案Agent 输出泛泛而谈状态节点过粗没有检查项把每个节点拆出明确的检查项和判断依据流程执行到一半跑偏上下文里塞了太多无关资料分层管理上下文核心步骤只放必要信息Agent 跳过关键步骤验收标准只查最终输出不查过程把关键中间产物也纳入输出要求同一个流程不同人用差异巨大输入协议不严格各猜各的强化输入校验缺失信息时先确认再执行skill 改了 A 坏了 B缺少回归测试用例每次修复都补一条金标准用例Agent 在应该停下的时候继续做没有兜底策略显式写明停止条件、确认条件、保守答案条件6.2 最常翻车的两个误区过度封装和上下文污染写 skill 写了三个多月之后我踩过最深的坑有两个。第一个是过度封装。一开始我恨不得把每个专业判断都写成规则比如“如果函数超过 50 行就报可维护性问题”结果 Agent 变成了一个死板的检查机器反而丢掉了模型本身对语境的理解能力给出一堆教条式意见。后来我把规则改成“如果函数过长检查它是否承担了多个职责若有则建议拆分若职责单一则提示补充注释即可”效果马上好了很多。skill 不是要把模型变成一个完全确定性的程序而是给它的专业判断加轨道让它跑得更稳不是让它失去判断力。第二个是上下文污染。我一开始把 skill 定义文件写得和参考资料合在一起Agent 每次执行都要读取一大坨内容结果执行到后面总是把参考案例当成当前任务来回应。解决方式就是前面说的三层结构定义文件精炼短小任务状态动态写入参考资料按需检索。这个经验对长流程的 skill 尤其重要一定要尽早把上下文章节分开。6.3 一个长期思考skill 不会替代人它替代的是经验传递的随机性最后说一个不太技术的观察。很多团队在引入 skill 的时候最大的阻力不是技术而是资深工程师的疑虑我把流程写成 skill会不会教会徒弟饿死师傅我自己做了一段时间之后最大的体会恰恰相反。skill 沉淀下来的是流程而流程是会迭代的。你把现有流程写下来之后反而更容易在真实执行中发现流程里的冗余步骤和逻辑盲区。流程本身变得可见、可评审、可改进这本身就是工程师个人能力的一次升级。我自己的经验是每次把流程写成 skill我都能在这个过程中发现自己以前做事其实有不少含糊的地方。把隐性经验显性化受益的不只是 Agent更是流程的缔造者本人。结尾的话如果只让我留一条建议那就是不要一上来就想做“全流程自动化平台”从一个最小的 skill 开始。比如把你最常用的一条审查流程写下来配上二十条金标准用例跑两个星期根据真实使用记录修三版然后再扩展下一个流程。技能树是一步步长出来的不是一次画出来的。我每次写 skill 都会在第一行加一句“什么时候不要用这个 skill”看起来是拦着自己的用户实际效果出奇地好能挡住一半误触发也让这个 skill 的适用范围从一开始就清清楚楚。