去年接手一个跨平台智能体项目时我踩了一个很典型的坑Demo跑通只花了两周真正的效率瓶颈不是模型能力而是“技能的沉淀”。每天都要把同样一段逻辑反复写进提示词里不同子任务的调参方式全靠脑子记新人接手还得重新摸索一遍。后来我花了几周时间把所有可复用的能力全部整理成了一套“skills”也就是技能模块整个项目的开发节奏才真正快起来。这篇文章想把这段沉淀过程里最核心的东西拆开讲清楚什么是技能、怎么拆、怎么写、怎么测、怎么维护以及中途踩过的那些坑。无论你是正在做Agent类应用的个人开发者还是团队里负责智能体功能落地的人这篇都值得你花十分钟读完。1. 项目里的“skills”到底指什么和一个写死的逻辑有什么区别我聊过很多做智能体项目的朋友发现大家对“skills”这个概念的理解差别非常大。最常见的情况是把技能、工具、提示词这三样东西混为一谈导致做出来的东西要么太薄要么太厚最后都很难复用。我这边给出的定义是技能是工具、提示词、上下文模板和校验逻辑的完整封装它对应的是“一个完整任务如何自动化执行”而不只是“模型能循环调用哪个函数”或“开场白该怎么说”。1.1 工具、提示词和技能三者不是一回事为了说清楚三者的边界我自己整理过一个对照关系放在项目文档里用了很久工具解决的是能力边界问题回答的是“智能体能不能做这件事”提示词解决的是表达质量的问题回答的是“这件事该用什么方式做”而技能解决的是任务闭环的问题回答的是“完成这个任务需要哪些能力和约束以及结果如何被验证”。举个例子如果项目里接入了一个文档解析服务那这个服务对应的“工具”就是暴露一个接口让智能体调用。提示词则是教模型“遇到PDF文件时先提取文本再按章节切割”。而一个技能会把这些全部组装起来它声明需要传入文件路径和解析粒度两个参数内置了完整的指示模板绑定了解析工具的调用权限还包含一条“解析结果超过多少页需要分段摘要”的校验规则。这样一套东西才算得上是一个技能而不是一个函数。我之前见过一种翻车做法把工具的返回结果直接用强规则写进业务流程里模型只能拿到结果完全看不到中间发生了什么。结果只要上游服务调整字段整个流程就瘫痪。技能化的价值就在于它把“不确定的模型行为”收敛成“确定性的交付物”让每个环节既能独立调试又能被组合使用。1.2 技能化要解决的三个真实问题第一个问题是效率问题。没有技能库之前写一个新功能要从空白的提示词开始每增加一个功能点可能就要把前面几轮对话重新调一遍非常浪费时间。有了技能之后很多子流程直接装配就能上改动集中在参数层。第二个问题是稳定性问题。模型的输出天然有随机性但很多业务流程需要稳定结构。技能模块可以把校验逻辑封装在里面输出不符合预期时触发重试或降级策略。我之前跑过一组测试未封装技能的场景下结果字段完整率只有七成封装后稳定在九成五以上。第三个问题是协作问题。团队里不同人写的提示词风格差异很大有人喜欢极简有人喜欢写一堆“严谨一点”“专业一点”的套话。技能化之后大家都按统一的元数据格式提交评审和替换都在模块层面完成不再互相拉扯。这也是技能体系和“一堆散落的提示词文件”之间最大的区别——它有结构、有边界、可测试。2. 技能拆分从业务需求到一份合理的技能清单技能拆分是整个体系里最讲究经验的部分把它放在首位不是因为实现难而是因为它决定了后续所有工作的天花板。拆得科学后面开发和维护都很顺拆得随意每个技能都会变成一个大杂烩组合时互相打架最后只能重做。2.1 自顶向下的拆解路径先看完整流程再看子任务我是从端到端流程开始拆的。比如做一个“内容发布智能体”我会先把整条流程画出来选题获取、资料检索、初稿生成、事实核查、风格改写、排版适配、发布执行。然后逐个判断这些环节是否可以交给一个稳定、独立的技能来完成。原则是一般性的越靠工具能力越容易做成技能越是依赖大模型“自由发挥”的部分就越需要单独抽出指示模板来约束。这种拆法有一个特别大的好处每个技能都有明确的上下游。因为你在拆解的时候就已经把流程图中每个节点的输入输出关系做了梳理所以等技能真正实现时接口设计就不会乱。我见过有人先写了技能代码再反推流程结果每个模块都在偷偷读取一个全局变量到最后完全理不清数据从哪里来。2.2 判定一个子任务是否值得独立成技能不是所有子任务都值得封装成技能。我用三条硬性标准来判断第一是可复用性。这个子任务是否会在两个以上的不同流程中出现。如果某个任务只在特定流程里出现一次那直接写在主流程里就好封装成技能反而增加跳转成本。第二是输入输出的稳定性。技能需要一套清晰的参数接口如果输入内容变化极其随意输出格式也五花八门那说明这个任务还没收敛成技能的基础。第三是验证的可行性。只有当任务有客观的验证手段比如字段完整性、数值范围、格式匹配你才有办法写校验规则否则技能质量无法被持续管理。为了更好说明我做了一张对照表每次不确定时都会翻一下判断维度值得拆分不值得拆分复用范围两个以上流程需要只在某一专项里出现输入接口参数可枚举、类型明确依赖大量上下文自由度高输出结构有固定字段和格式输出类型多变任务本身无统一评价标准验证手段可以脚本化校验只能人工看效果2.3 拆分时最容易踩的两个边界问题边界问题集中在两个极端技能太大和技能太小。技能太大表现为什么就是把“生成一篇行业分析报告”整体做成了一个技能内部塞了检索、分析、大纲、写作、排版、图表生成等六七个环节。这种技能表面上用起来方便但内部耦合极高某环节一旦调整整个模块都要跟着变。最要命的是它不适合组合——别的流程想复用其中“大纲生成”的能力要么复制代码要么再拆一份等于没拆。技能太小呢就是原子化到“生成一句总结”“拆分一段文本”这种粒度。这种微技能虽然边界清晰但使用方需要自己组装大量调用组合逻辑反而比写在主流程里更复杂。我的经验是以“能否用一句话说清这个技能交付了什么结果”为判断线如果说得清大小基本合适如果说出来还要加一堆前提说明粒度没选好。3. 技能落地把脑子里想清楚的“技能”变成可执行模块拆分只是规划落地的过程才是真正动代码、动文档的阶段。这个阶段要解决的问题是你希望智能体在执行某个任务时到底按什么逻辑去调用一个技能模块以及这个模块本身应该保持什么样的结构。我自己的做法是给每个技能建立一套标准文件结构涉及元信息、指令、引用和校验四块内容缺一不可。3.1 技能模块的标准结构元数据、指令、工具引用与校验我给团队定过一套模板组织上就四个部分。元数据负责描述“我是谁、我能做什么、我能接受什么样的参数”指令模板负责描述“具体任务该怎么执行、有哪些硬性要求”工具引用负责让技能可以调用外部接口或本地能力校验规则负责保证“输出的结构没问题、流程达到预期”。这里有一个被很多人忽略的点元数据里的“描述”字段影响极大。因为智能体是靠描述来决定什么时候调用这个技能的如果描述写得模糊比如“处理文件”那模型可能在任何跟文件相关的场景里都触发它如果描述写得太窄真正需要时又不会触发。我建议描述里写清楚适用场景、典型输入样例和明确不适用的场景宁可多写几行不要偷懒。3.2 写指令模板的核心技巧少用咒语多用分支指令模板是一份说明性文本它的核心目标不是用语气词讨好模型而是用清晰的分支提供行为约束。我发现很多开发者在模板里堆砌了大量的“扮演某某专家”“发挥你的创造力”这种风格在简单聊天场景下有效但在任务执行型技能里很容易带来输出漂移。我自己在写技能指令时一般按照“目标说明、步骤概览、分支处理、输出格式”四段来组织。比如一个“会议纪要提炼”技能我会写清楚这次任务是把录音转写稿提炼成待办事项步骤是先过滤口水话再按议题归类再提取责任人和截止时间分支处理包括“某人明确承诺了某事但没给时间需标注待确认”以及“同一事项多次讨论取最后结论为准”最后明确输出字段。整段不会有夸张的修辞但行为约束非常具体。关于示例的数量我踩过不少次坑。给模型看三五个精选的正反例效果通常最好。我见过有人把一个技能塞了几十个示例进去模型反而学会了机械复制输出几乎和示例一致换个场景就出问题。示例的作用是建立模式和格式感不在于穷举。3.3 参数接口设计少用隐含变量多用显式参数参数接口决定了技能的复用面有多大。我的原则是接参只允许通过参数列表或标准上下文传入不允许技能内部直接读取外层对话的历史记录。这一点特别重要。曾经有一次调试一个技能内部悄悄读取了对话历史里的用户ID去做日志记录看起来没问题但技能被复用时就拿错了用户数据查了很久才发现。参数设计上我没有走特别复杂的路线就是把参数分为三类必填参数、可选参数和默认值参数。比如“生成业务周报”这个技能必填参数是本周数据和上周数据可选参数是语气偏好默认值参数是报告模板名称。每加一个参数我都会在元数据里补充字段说明并且给出一个真实的示例值。这样在多人协作时别人不需要翻主流程源码就知道该传什么。4. 技能组合多个模块放到同一执行流程里如何协作单独做一个技能不难难的是多个技能进入同一条流水线时编排、冲突和接口问题一起冒出来。这是我在实际项目里耗时最多的部分几乎一半的返工都发生在这里。4.1 管道模式上一个技能的输出必须是下一个技能的输入最自然的组合方式就是把技能排成管道先做数据清洗再做字段抽取再生成摘要最后输出结构化结果。管道模式的好处是每个环节都是独立函数可以用固定样例分别测试。它的要求也很严格上游输出的字段名、类型必须和下游参数完全对齐。这里常出问题的地方就在于你以为对上了实际上没有。举个例子某个清洗技能输出字段叫“processed_text”下一个技能参数里却叫“text_content”运行时直接报参缺失。后来我要求所有技能的接口定义里上游必须把输出样例贴一份到下游的测试用例里这个问题才彻底根治。管道模式不适合出现环状依赖我实际排流程时也会刻意避免让两个技能互相调用。4.2 并行与条件分支提高效率的两种组合技巧有些互不依赖的技能可以并行跑尤其在一个流程里既有文本摘要又有关键词提取时并行可以有效压缩整体耗时。我之前在某个跨平台系统的内容分析模块里把两个独立技能拆到并行执行整个链路的耗时差不多减少了一半。不过并行执行要注意输出合并逻辑两条分支的结果如何合并成一棵统一JSON结构这个必须提前设计好。条件分支用来处理“看情况走哪条路”。比如内容审核流程里先判断文本是否命中高危词如果命中就走人工复核技能否则走自动放行技能。这里用的是路由逻辑路由本身通常是普通代码不一定要做成技能。很多人非要给路由也包一层技能结果反而增加了一层不必要的模型调用速度和稳定性都在下降。4.3 冲突与优先级一次真实的“技能打架”复盘我印象很深的一次问题是两个技能命名空间冲突。同一批数据既被“信息抽取技能”写入了字段“category”又被“标签推荐技能”写入了同名但含义不同的字段。后面的技能覆盖了前面的导致下游拿到完全错误的分类信息。排查了两天才发现是字段名重复。现在的做法是每次新增技能时都要做一次全局字段名注册。先在注册表里查重确认无冲突再进入开发环节。另一个经验是给每个技能定义明确的优先级级别当一个技能执行失败时是重试它本身还是降级到另一个更基础的技能这个决策逻辑要放在编排层而不是技能内部。下面这张表是我在做编排时经常参考的决策清单情况处理方式下游请求参数不存在检查上游注册的输出字段名某技能连续失败两次切换降级方案记录日志后继续输出结构合法但内容为空按校验规则判定为低置信度进入人工队列两个技能提交同名输出字段全局字段注册表查重拦截5. 技能维护版本、测试和迭代的长期功课技能不是写完就完事它是需要维护的资产。我在项目后半段最大的体会是技能库真正值钱的地方不在于一开始设计得多漂亮而在于后续能不能做到可控的迭代。没有版本意识、没有测试和回退机制技能库只会越用越烂。5.1 版本管理语义化版本号和变更理由缺一不可我给技能库引入了一套非常简单的版本策略主版本号表示不兼容的接口变更次版本号表示向后兼容的功能变更补丁号表示内部修正。任何一个技能升级时“变更日志”里都必须写清楚为什么改、影响范围是什么、需要配合改哪些下游模块。我见过一个团队在升级技能时只改了代码没同步任何说明结果下游流程全部还在用旧的参数习惯引发大面积回归。我自己现在要求所有技能变更都附带一个简短的变更说明哪怕只有五行也要写清楚“加了什么参数删了什么依赖下游需要注意什么”。光这一个习惯就避免了好几次线上事故。5.2 测试技能静态测试、功能测试和回归测试技能测试要从三个层面来做。静态测试检查元数据和参数定义是否规范比如描述字段是否填写、参数是否有样例值、引用的工具是否存在。功能测试用一组固定的输入样例跑一遍观察输出是否满足预期结构这里通常不需要模型回答得多“惊艳”只需要稳定。回归测试则是在修改完技能后把历史关键样例全部跑一遍确保旧场景没有被改坏。实际做的时候我会把测试样例分成三批基础样例、边界样例、异常样例。基础样例保证正常流程边界样例覆盖长文本、空输入、特殊符号这类情况异常样例用于验证技能拿到不合法输入时不至于崩溃能返回一个可理解的错误信息。之前就是因为没测边界样例某个技能在大输入下直接超时导致整个流程卡死。5.3 真实项目里遇到过的三个典型反模式第一个反模式是“示例过多导致机械复制”。我在前面提到过为了追求效果曾经把一个技能塞进了几十个示例结果模型在所有情况下都按第一个示例的模板输出参数里的变化项完全被忽略。解决办法是精简示例只保留有代表性的三个并且搭配“如果遇到与示例不一致输入时按规则处理”的说明。第二个反模式是“技能依赖全局状态”。某个技能直接使用了外层环境的某个配置项导致这个配置一改技能在几十个流程里的表现全部变化。正确做法是把配置当作显式参数传进来这样依赖关系一目了然。第三个反模式是“大技能长成怪物”。随着需求变化不断往技能里加规则最后整个指令模板上千行内部逻辑互相矛盾直到测试样例都无法覆盖时才发现问题。6. 技能体系的分层架构与团队协作实践技能发展到一定数量后必须有一个分层视角否则任何人都没法在几十上百个技能里快速定位要找的那个。我比较推荐的架构是三层的体系基础能力层、领域技能层、编排层。6.1 三层架构帮团队快速定位和沉淀技能基础能力层对应的是那些通用、无领域属性的操作比如文本切分、PDF解析、数据清洗、格式转换。领域技能层则是针对具体业务场景的封装比如此前讲的内容审核、报告生成、会议纪要提炼。编排层一般不直接执行具体事务而是把多个技能按流程组织起来形成一套完整的业务能力接口。这个分层的好处是新人加入时可以快速建立心智路线图。看到任务先走一遍审核技能再走向报告生成技能定位效率高很多。另一个很实际的收益是基础层的技能越攒越多后续很多新业务都可以靠组合基础技能来快速构建不用从零开发。6.2 团队技能库的建设流程我们在项目组内建了一个共享技能库并且确定了“提出、审核、发布、废弃”四步走流程。任何新技能都必须按统一目录结构提交由指定的人员做代码评审和样例测试通过后发布到共享区。这里有一个容易踩坑的地方技能库如果缺乏审核流程很快就变成垃圾场。我见过有人直接把一个临时调试用的草稿技能传上去结果一轴流跑它浪费了大家半天时间。技能文档的技术细节之外我还会要求提交人在描述里写明“使用这个技能的前置条件”“已知局限”和“推荐的使用场景”。没有这些上下文单独看功能示例很容易误用。比如“摘要生成”技能如果没有标明不适用于代码注释摘要其他同事很可能拿它去处理代码片段效果当然很差。6.3 定期评审技能库也需要“瘦身”技能库维护需要我们定期做一次全面评审。我的做法是每两周花一个小时统计每个技能最近的使用频次和平均成功率把那些长期没有被调用的技能标记为“休眠”状态把成功率持续偏低的技能退回改造。这一步虽然会带来一些沟通成本但它避免了技能库越滚越大、垃圾越堆越多的问题。进行了一段时间后我也学会了区分“暂时不用的技能”和“无效技能”。暂时不用的可以保留标注休眠状态无效技能比如有替代方案、逻辑已经过时的就要直接下线避免误导后来人。真实项目里一个场景的处理逻辑很可能修正过很多次如果只更新技能不看关联技能旧版本的“兄弟技能”就会继续在外面流窜这是最让人头疼的维护难题之一。7. 从最小技能开始慢慢长出你的技能树最后说点个人体会。做技能这件事技术本身不复杂真正难的是抽象能力。你需要从当下的具体任务里看出哪些环节具备复用价值然后冒着“暂时无法立刻见效”的风险把它沉淀下来。我见过很多开发者刚开始就在做很大的技能库设计搞了一堆复杂的方法论结果连一个最小的技能都还没写顺最后不了了之。如果你想在自己的项目里尝试我建议先把一个小流程做成一个最小可用技能真的跑通、真的稳定、真的被别人用起来然后再逐步扩充。等到技能树真正长出来的时候你再看整个项目的交付节奏就会明白前面这些准备工作全都是值得的。