1. 为什么“技能化”才是Agent落地的核心先说个直观感受。过去一年里我见过太多Agent项目大家一开始的兴奋点都集中在“模型多聪明、能听懂多复杂的指令”实际一上线就傻眼——模型确实能聊但让它稳定干成一件事难。你反复调prompt今天好用明天翻车换一个输入场景又崩。问题出在哪出在你把Agent的能力寄托在“一次性对话”上而生产环境需要的是能拆、能测、能组合的“技能单元”。Agent Skills这个概念简单说就是给智能体准备一套可复用的技能库让模型在合适的场景调用合适的工具而不是每次都从零开始现场发挥。这篇文章想聊的就是围绕agent-skills这个方向从设计思路到落地实现把一套技能体系从无到有搭起来的完整过程。不聊虚的给你可以直接抄走的结构、代码、坑点。适合正在做Agent应用开发、想把AI能力做成稳定产品的工程师也适合刚入门但不想走弯路的朋友。为什么技能化这么关键因为一个Agent能跑通demo和能上线是两码事。demo阶段你可以依赖模型的临场能力生产环境你必须把每一个“动作”变成可验证、可回滚、可观测的模块。把能力拆成技能本质上是把“模型的想法”变成“工程的事实”。1.1 从“写提示词”到“建技能库”的思维转变早期做Agent我们的工作方式基本是一个系统prompt把所有规则写进去然后祈祷模型理解。后来发现这条路走不通。一个复杂的业务场景比如“帮用户处理报销单”里面的动作可能包括识别发票信息、核对报销标准、计算金额、生成审批单、发送通知。你要把这些全部塞进一段prompt里模型的注意力会被稀释规则之间还会相互干扰。换成熟练工的做法之后我最大的体会是prompt负责的是“什么时候用哪个技能”技能本身负责“把这件事做对”。这两个层次分开之后整个系统的稳定性立刻上来了。每个技能就是一个独立的小程序有明确的入参、出参、错误码。模型要做的只是根据用户意图选择一个或多个技能组合调用剩下的执行逻辑全部由代码保证。哪怕模型选错了技能你也能从日志里定位到具体环节而不是对着一个黑盒式的回答干瞪眼。这个转变说起来轻巧实际上意味着整个工程组织方式的调整。你的代码仓库不再是一个大而全的Agent应用而是一个个技能模块的集合外加一个负责路由和调度的Agent壳。仓库结构会变成类似这样的形态agent-skills/ ├── skills/ │ ├── invoice_ocr/ │ ├── expense_check/ │ └── email_sender/ ├── agent/ │ ├── router.py │ └── context.py └── tests/1.2 技能化带来的三个硬收益第一可测试。传统prompt的方式没法做单元测试你只能端到端地“试”。技能化之后每个技能都有确定的输入输出契约你可以为它单独写测试用例。发票识别技能传入一张样张图片断言返回的金额字段是否正确费用计算技能传入几个明细条目断言总额和校验规则。这些测试跑在CI里每次改动都回归一遍踏实。第二可编排。复杂任务不再是单次对话能搞定的而是多个技能按照流程组合执行。比如报销场景先调用发票识别拿到结构化信息再调用费用校验判断是否符合公司标准最后调用通知服务把结果推送给审批人。技能间通过明确的输入输出衔接像流水线一样。其中一个环节出问题只需要替换或回滚对应的技能不需要动整个系统。第三可分享。技能的粒度是标准的就可以像npm包、pip包一样在团队内部甚至社区里流通。我在实际项目中就复用过别人写好的PDF解析技能省掉了自研的不少工作量。技能化之后Agent能力的增长方式从“每次重新发明”变成了“不断积累资产”这个杠杆效应才是长期价值所在。2. Agent技能库的整体设计思路说完为什么进入怎么做。技能库不是简单地把一堆工具函数塞给模型它的设计质量直接决定Agent执行的可控性和稳定性。我把一个合格技能拆成了四个组成部分描述、Schema、执行逻辑、测试用例。这四部分各司其职缺一个都会出问题。2.1 一个技能的四个核心组成部分描述Description这是写给模型看的说明这个技能在什么场景下使用、接收什么参数、输出什么结果。描述写得不好模型要么在不需要的时候乱调用要么需要的时候不知道用。判断标准很简单把这个描述丢给一个刚入职的新同事他能不能准确判断什么时候该用、什么时候不该用。Schema严格定义输入输出的数据结构。我建议输入用JSON Schema定义字段名称、类型、是否必填、枚举范围都写清楚。这一步是给模型戴上的“紧箍咒”也是给执行层做校验的依据。很多Agent出错根子就出在Schema定义含混模型传了个不存在的字段或者参数类型对不上。执行逻辑实际干活的代码可以是本地函数、外部API调用、数据库查询等。执行逻辑要保持“尽量纯粹”——即给定相同输入产生相同输出避免依赖会话级状态。一个技能内部可以有自己的缓存或临时数据但对外暴露的接口应该做到幂等可重放。测试用例每个技能至少配两个用例——一个正常路径、一个异常路径。正常路径验证理想情况下的行为异常路径验证输入非法、外部服务不可用等情况下的容错表现。测试用例不仅服务于回归更重要的是它倒逼你把技能的边界想清楚。2.2 技能描述怎么写才不坑这是我在实战中踩坑最多的地方。技能描述决定模型的选择但模型对描述的理解方式跟人不太一样。我总结出一套相对稳定的写法核心是三段式场景、输入条件、禁忌。场景部分直接说明“什么时候用这个技能”。比如发票识别技能的描述可以这样写用于从图片或PDF中提取发票信息。当用户提供报销单、购物小票或电子发票截图时调用此技能获取结构化数据。输入条件部分要给出触发的最低要求。如果用户只说“帮我报销”但没给图片这个技能就不该被调用。所以加上一句“缺少原始图片或文件时不要调用此技能先请用户提供”。禁忌部分是我后来才加上的效果却出奇地好。每个技能我尽量想清楚哪些场景它绝不能做写死在描述里。比如费用校验技能就注明“本技能仅适用于员工日常报销不含差旅预订差旅相关费用需走差旅管理模块”。写法上还有一个细节描述不要出现过多同义词替换。实测下来用词统一反而能让模型更稳定地触发匹配。有些开发者为了SEO式地优化描述把“报销”写成“费用申请”“支出申报”“财务报销”结果模型在边界场景里就开始飘了。技能描述是工程文档不是营销文案用户怎么说就怎么写保持直接。2.3 技能要不要带状态纯函数优先原则设计技能时最容易犯的一个错误是顺手把状态管理也塞进去。比如一个“保存用户偏好”的技能内部维护了一个全局变量多个调用之间共享状态。这在单次调试时看不出来问题一旦Agent并发执行多个任务状态就串了。用户改了A偏好B任务读取时拿到的是A的莫名其妙。我的原则是技能默认做成无状态纯函数所有外部依赖通过参数显式传入。如果确实需要跨调用保存数据比如记用户上次查询时间把这个状态存到外部存储数据库、Redis而不是技能内部的全局变量。输入参数里带上上下文ID执行时从存储中按ID读取并更新。这样技能可以随时重放、随时回滚不会因为状态残留产生脏数据。3. 从0到1实现一个完整技能的实操记录理论说了一堆拿一个具体例子走完整流程。我选一个大家日常都需要的场景整理会议纪要。需求描述一下给一段杂乱的中文会议语音转写文本输出一份结构化的会议纪要包含讨论主题、关键决定、待办事项与负责人、下次会议时间等。这个技能的开发过程能够覆盖我在前面提到的全部设计要点。3.1 需求拆解与技能边界确认第一步不是写代码而是把需求边界划清楚。会议纪要整理这个需求看似简单里面的坑不少。我需要明确几个问题输入是纯文本还是音频文件如果输入是音频文件需要先去调用一个语音转写技能这不是本技能该做的事。我明确本技能的输入是“语音转写后的文本”。输出格式是固定模板还是自由段落我采用固定模板因为后续可能接入其他系统比如同步到项目管理工具固定结构更利于程序化处理。是否需要支持中文以外的语言首版只支持中文描述里明确说明“不支持英文及其他语种不要强行翻译”。会议纪要的“待办事项”需要负责人如果原文没提到负责人怎么办不编造标记为“未指定”。把边界想清楚之后技能的输入和输出Schema就呼之欲出了。我先把技能文件结构搭起来skills/meeting_minutes/ ├── MY.md ├── schema.json └── main.py各文件用途说明一下。MY.md是这个技能给模型看的“说明书”相当于技能的身份证和使用指南schema.json定义输入输出契约main.py是实际执行逻辑接收schema校验后的参数返回格式化结果。这样每个技能都可以独立测试、独立发布。3.2 技能的三个关键文件到底写成什么样先看MY.md这是模型决定是否调用本技能的依据我用的是前面说的三段式写法# 会议纪要整理技能 用于将一段中文会议语音转写文本整理为结构化会议纪要。 ## 适用场景 - 用户提供会议录音转写文本纯文本希望得到清晰的会议结论 - 输入文本包含讨论过程、决定、待办事项等混杂内容 ## 输出格式 - markdown格式的结构化纪要包含会议主题、参会角色、关键讨论点、决定事项、待办事项含负责人与截止时间、下次会议建议 ## 禁忌 - 输入为音频文件时不要调用应先进行语音转写 - 输入为非中文文本时不要调用不要强行翻译 - 原文没有明确提到的信息如负责人、时间不要编造统一标记为“未指定”接下来是schema.json。这里定义技能接收的输入参数和返回的结果结构{ name: meeting_minutes, description: 从中文会议转写文本中提取结构化会议纪要, input_schema: { type: object, properties: { raw_text: { type: string, description: 会议语音转写文本支持中文, minLength: 20 }, meeting_title: { type: string, description: 会议名称可为空为空时根据内容自动生成, maxLength: 50 } }, required: [raw_text] }, output_schema: { type: object, properties: { success: { type: boolean }, summary: { type: object, properties: { meeting_title: { type: string }, key_points: { type: array, items: { type: string } }, decisions: { type: array, items: { type: string } }, action_items: { type: array, items: { type: object, properties: { task: { type: string }, assignee: { type: string }, due_date: { type: string } } } } } } } } }main.py是核心执行逻辑。在这个例子里我用一个大模型调用来完成从“杂乱文本”到“结构化数据”的转换。但要注意这里的Agent框架调用和技能本身的执行是两个层面技能内部的模型调用是“该技能自己的实现细节”而不是整个Agent在做决策。这样设计的好处是即便将来我们换了底层大模型或者改成规则模型混合方式技能对外的输入输出契约不用变。main.py的核心结构如下import json from typing import Dict, Any def execute(inputs: Dict[str, Any]) - Dict[str, Any]: raw_text inputs.get(raw_text, ).strip() meeting_title inputs.get(meeting_title, ).strip() if len(raw_text) 20: return {success: False, error: raw_text length too short} # 调用内部大模型做结构化提取 # 这里省略实际请求代码关键点在于prompt工程 result llm_extract(raw_text, meeting_title) # 对结果做后处理必填字段缺失时补未指定 for item in result.get(action_items, []): item.setdefault(assignee, 未指定) item.setdefault(due_date, 未指定) return {success: True, summary: result}这里有一个容易被忽略的点从模型拿到的原始输出往往结构不稳定比如JSON里某个字段缺了、数组格式不对。因此每个技能执行逻辑里必须有一个“结果规整”的步骤把模型的自由输出强行归一到schema定义的结构内。我的做法是对关键字段逐个做校验和兜底赋值宁可多写几行也比下游解析报错强。3.3 接入和验证三步走逐个环节确认技能写完之后不要急着整套上。我的习惯是先做三个层级的验证每一层通过再进下一层。第一层验证技能描述是否能被模型正确理解。把MY.md放到一个空的Agent里随机给若干条用户消息观察模型是否在“应该调用”的场景选择本技能、在“禁止调用”的场景不触发。这步可以自动化跑一批模拟对话但至少前两轮建议人工过一下。第二层验证Schema是否能被正确解析。这一步最容易出错的是参数类型。比如raw_text我用string类型长度限制minLength20但如果模型传了个空字符串框架应该返回校验失败而不是继续执行。这里我建议在入口处再写一道防御校验不依赖框架自带逻辑。第三层验证执行结果能否被下游使用。输出是给下游消费者用的不只是给模型看的。我在这一步会单独写一个小的消费者脚本把技能输出直接喂给后续流程比如自动同步到日历或项目管理工具确认格式真正兼容而不是肉眼看个大概。以下是这三步的清单式整理步骤一角色行为测试——确认描述触发准确不出现乱调用步骤二入参出参校验——边界输入空文本、超长文本、缺字段是否稳定返回错误而非崩溃步骤三端到端消费测试——输出结果能被下游系统直接消费并展示正确三步跑通这个技能才算“能用”。很多团队省掉了步骤一和步骤三导致技能本身逻辑没问题但模型就是不按预期调用或者输出格式跟下游不匹配这种问题排查起来最费时间。我在实际项目中把这三个步骤写成了一套本地脚本每次新增或修改技能都跑一遍省了大量联调时间。4. 从单技能到技能编排复杂任务的组合方法单个技能解决的是“一个动作”但真实业务里Agent要完成的往往是一连串动作。比如“帮我处理今天的报销”先识别发票再校验金额再填入报销单最后发通知。这就是技能编排。这个环节处理得好不好直接决定Agent在复杂任务中的可用性。4.1 编排的三种基本模式技能编排跟写程序的控制流其实是同构的核心就三种模式顺序执行、条件分支、循环处理。顺序执行是最常见的。一个技能的输出直接作为下一个技能的输入。典型场景是报销发票识别输出结构化发票字段费用校验技能读取字段按规则判断是否合规输出的结论再交给报销单生成技能。每个环节之间通过一个“数据总线”传递JSON对象。我这里建议把中间数据都打日志出问题方便回放。条件分支用于“根据情况走不同路径”。比如会议纪要技能输出的action_items里如果某个任务标记了due_date就走“创建日历提醒”分支如果due_date缺失就走“待补充”分支或者直接生成一条追办消息。条件分支的实现可以在Agent的路由逻辑里写if/elif也可以用模型来做决策。我的经验是能写死就写死模型判定的稳定性在关键业务路径上不够用。只有真正无法预先枚举的情况才让模型判断。循环处理用于批量场景。比如一次整理10天内的所有会议纪要——先循环调用会议纪要整理技能处理每一天的文本再把结果合并成一份周报。循环要注意两个坑一是技能调用的错误处理某一天的数据处理失败了不能中断整个循环二是总量控制单次Agent任务里技能调用次数要做上限防止死循环或者费用失控。4.2 复用第三方技能库安全与适配经验技能化做起来之后很快就有团队把内部技能沉淀成共享库社区里也出现了一批开源技能集合。复用别人的技能能省不少时间但不是直接拷进仓库就完了。我自己的检查清单包括这么几项。第一看描述和schema是否匹配。有些第三方技能的MY.md描述很强schema却很简陋实际调用会发现模型老传错参。遇到这种情况宁可自己改造schema再上别图省事。第二看执行逻辑有没有隐藏的副作用。检查代码里是否访问了环境变量、是否有网络请求、是否有写操作。如果某个技能内部偷偷调了一个外部API、还带了硬编码的token这本身就是安全隐患。我在审查第三方技能时直接搜索代码中的token、password、api_key等关键词发现一个踢掉一个。第三限定执行权限。Agent在执行技能时建议跑在受限环境里比如容器内无root权限、网络访问走白名单、磁盘写入限指定目录。这个建议在早期项目里容易被忽略等真正出了问题比如技能误删了文件就来不及了。权限收紧 日志留存双管齐下。4.3 版本管理与技能演进技能是有生命周期的。业务规则变了比如报销额度调整、底层模型升级提示词效果变化、外部依赖变了API接口更新都要求技能同步迭代。我在这方面的做法参考了普通软件发布的流程但做了简化。每个技能目录里放一个CHANGELOG.md每次修改记录三个东西改了哪个文件、为什么改、影响范围是什么。然后在Agent的路由配置里指定技能版本号例如当前使用v1.3的meeting_minutes没验证过的不直接上生产。这里用版本号的好处是某次业务方反馈“会议纪要突然格式不对了”我能从版本记录里立刻知道上一版和这一版改了什么而不是靠回忆。灰度上线也值得提一句。对于流程类技能发送邮件、写数据库如果改动涉及执行逻辑我会让系统在最初10%的流量里使用新版本观察错误率和调用失败率确认稳定再全量放开。纯文本处理类技能可以放宽但涉及外部动作的技能务必保守。5. 技能开发路上的高频问题与排查实录技能开发是个实践活踩坑在所难免。我把自己在项目里反复遇到的几类问题整理成了一份排查速查表每一条都是真金白银换来的。5.1 模型“无视”技能规则该怎么排查最让人头疼的问题技能描述明明写得清清楚楚测试用例也跑了模型在某些输入下就是不调用该调用的技能或者调用时传参完全不合理。遇到这类问题我会按顺序排查四个环节。首先检查描述和Schema是否冲突。比如描述里说“必须提供用户ID”但Schema里没有user_id字段模型自然无所适从。其次检查技能数量Agent身上挂的技能太多超过15个时模型的选择准确率会显著下降表现为“漏调”。第三检查输入历史模型的调用决策受上下文长度影响当对话历史太长前面的技能描述被截断或权重降低也会导致漏调。最后检查模型参数设定——温度是否设得过高tool_choice是否被误设为none这两个参数改动对调用行为影响极大。实际排查案例我有一次遇到“费用校验技能死活不被调用”日志显示Agent直接跳过校验去生成报销单了。查了一圈最后发现是技能列表里有个新加的技能描述里包含了“校验”字样模型混淆了两个技能。解决方式是在费用校验技能的描述里加上一句“本技能是所有报销流程的必经环节在生成报销单之前必须调用”问题立刻缓解。这个经验告诉我技能描述的互斥性要显式声明模型才不会搞混。5.2 技能超时、重试与幂等设计的实操经验外部API调用类技能超时和重试是必答题。最简单的实现是设一个超时时间我常用10秒作为上限超时后重试。但如果重试策略不对可能引发更严重的问题——重复扣款、重复发送。幂等设计的核心思路每次任务生成一个唯一的request_id技能在执行外部写入操作前先检查这个request_id是否已处理过。比如发送邮件技能执行逻辑先查数据库是否存在该request_id对应的发送记录有就直接返回上次结果没有才真正发信。这个模式实现成本不高却能消除大半因重试导致的脏数据问题。重试次数方面也要克制。我的经验是外部API最多重试2次第一次等待1秒第二次等待3秒再失败就返回错误信息让Agent换个策略。无限重试只会让系统在外部服务故障时陷入无意义的等待。另外强烈建议给技能的执行时间加上总的超时熔断某些技能陷入了死循环靠外部的熔断机制才能兜底。5.3 技能冲突、命名空间与数据隔离技能数量上来之后冲突问题会浮出水面。最常见的是同名参数不同含义。比如邮件发送技能和消息通知技能都有一个to字段一个是收件地址一个是接收人ID模型传参时容易搞混。我的处理方式是给每个技能的参数加技能名前缀比如email_to和notify_recipient从命名上杜绝交叉。数据隔离则要关注多用户场景。Agent可能同时服务多个用户技能执行时如果不能确保数据按用户隔离就会出现严重事故。我的做法是在技能入口传入一个context对象里面包含user_id和session_id执行逻辑所有数据读写都挂在user_id维度下。严禁在技能内部使用无标识的全局缓存。这几个问题罗列出来不复杂但每一条背后都有排查数小时的代价。我把它们写成了一张速查表放在团队的技能开发规范文档里新成员做技能开发前先过一遍能少走很多弯路。个人最大的感受是技能库的成熟度不取决于技能数量多少而取决于每个技能的设计是否克制、边界是否清晰。与其塞进去100个含糊的技能不如先打磨好20个经得起测试的技能。测试用例、版本记录、权限隔离这些工程手段才是让Agent从“玩具”变成“工具”的真正的分水岭。最后分享一个小习惯每写完一个技能我都会手动构造几个“边界刁钻”的输入跑一遍比如超长文本、纯符号输入、完全无关的内容。这些边界用例往往比正常用例更能暴露问题做多了你会发现技能系统的稳定性就是这样一点一点磨出来的。
Agent技能库从0到1：构建可复用、可编排的智能体技能体系
1. 为什么“技能化”才是Agent落地的核心先说个直观感受。过去一年里我见过太多Agent项目大家一开始的兴奋点都集中在“模型多聪明、能听懂多复杂的指令”实际一上线就傻眼——模型确实能聊但让它稳定干成一件事难。你反复调prompt今天好用明天翻车换一个输入场景又崩。问题出在哪出在你把Agent的能力寄托在“一次性对话”上而生产环境需要的是能拆、能测、能组合的“技能单元”。Agent Skills这个概念简单说就是给智能体准备一套可复用的技能库让模型在合适的场景调用合适的工具而不是每次都从零开始现场发挥。这篇文章想聊的就是围绕agent-skills这个方向从设计思路到落地实现把一套技能体系从无到有搭起来的完整过程。不聊虚的给你可以直接抄走的结构、代码、坑点。适合正在做Agent应用开发、想把AI能力做成稳定产品的工程师也适合刚入门但不想走弯路的朋友。为什么技能化这么关键因为一个Agent能跑通demo和能上线是两码事。demo阶段你可以依赖模型的临场能力生产环境你必须把每一个“动作”变成可验证、可回滚、可观测的模块。把能力拆成技能本质上是把“模型的想法”变成“工程的事实”。1.1 从“写提示词”到“建技能库”的思维转变早期做Agent我们的工作方式基本是一个系统prompt把所有规则写进去然后祈祷模型理解。后来发现这条路走不通。一个复杂的业务场景比如“帮用户处理报销单”里面的动作可能包括识别发票信息、核对报销标准、计算金额、生成审批单、发送通知。你要把这些全部塞进一段prompt里模型的注意力会被稀释规则之间还会相互干扰。换成熟练工的做法之后我最大的体会是prompt负责的是“什么时候用哪个技能”技能本身负责“把这件事做对”。这两个层次分开之后整个系统的稳定性立刻上来了。每个技能就是一个独立的小程序有明确的入参、出参、错误码。模型要做的只是根据用户意图选择一个或多个技能组合调用剩下的执行逻辑全部由代码保证。哪怕模型选错了技能你也能从日志里定位到具体环节而不是对着一个黑盒式的回答干瞪眼。这个转变说起来轻巧实际上意味着整个工程组织方式的调整。你的代码仓库不再是一个大而全的Agent应用而是一个个技能模块的集合外加一个负责路由和调度的Agent壳。仓库结构会变成类似这样的形态agent-skills/ ├── skills/ │ ├── invoice_ocr/ │ ├── expense_check/ │ └── email_sender/ ├── agent/ │ ├── router.py │ └── context.py └── tests/1.2 技能化带来的三个硬收益第一可测试。传统prompt的方式没法做单元测试你只能端到端地“试”。技能化之后每个技能都有确定的输入输出契约你可以为它单独写测试用例。发票识别技能传入一张样张图片断言返回的金额字段是否正确费用计算技能传入几个明细条目断言总额和校验规则。这些测试跑在CI里每次改动都回归一遍踏实。第二可编排。复杂任务不再是单次对话能搞定的而是多个技能按照流程组合执行。比如报销场景先调用发票识别拿到结构化信息再调用费用校验判断是否符合公司标准最后调用通知服务把结果推送给审批人。技能间通过明确的输入输出衔接像流水线一样。其中一个环节出问题只需要替换或回滚对应的技能不需要动整个系统。第三可分享。技能的粒度是标准的就可以像npm包、pip包一样在团队内部甚至社区里流通。我在实际项目中就复用过别人写好的PDF解析技能省掉了自研的不少工作量。技能化之后Agent能力的增长方式从“每次重新发明”变成了“不断积累资产”这个杠杆效应才是长期价值所在。2. Agent技能库的整体设计思路说完为什么进入怎么做。技能库不是简单地把一堆工具函数塞给模型它的设计质量直接决定Agent执行的可控性和稳定性。我把一个合格技能拆成了四个组成部分描述、Schema、执行逻辑、测试用例。这四部分各司其职缺一个都会出问题。2.1 一个技能的四个核心组成部分描述Description这是写给模型看的说明这个技能在什么场景下使用、接收什么参数、输出什么结果。描述写得不好模型要么在不需要的时候乱调用要么需要的时候不知道用。判断标准很简单把这个描述丢给一个刚入职的新同事他能不能准确判断什么时候该用、什么时候不该用。Schema严格定义输入输出的数据结构。我建议输入用JSON Schema定义字段名称、类型、是否必填、枚举范围都写清楚。这一步是给模型戴上的“紧箍咒”也是给执行层做校验的依据。很多Agent出错根子就出在Schema定义含混模型传了个不存在的字段或者参数类型对不上。执行逻辑实际干活的代码可以是本地函数、外部API调用、数据库查询等。执行逻辑要保持“尽量纯粹”——即给定相同输入产生相同输出避免依赖会话级状态。一个技能内部可以有自己的缓存或临时数据但对外暴露的接口应该做到幂等可重放。测试用例每个技能至少配两个用例——一个正常路径、一个异常路径。正常路径验证理想情况下的行为异常路径验证输入非法、外部服务不可用等情况下的容错表现。测试用例不仅服务于回归更重要的是它倒逼你把技能的边界想清楚。2.2 技能描述怎么写才不坑这是我在实战中踩坑最多的地方。技能描述决定模型的选择但模型对描述的理解方式跟人不太一样。我总结出一套相对稳定的写法核心是三段式场景、输入条件、禁忌。场景部分直接说明“什么时候用这个技能”。比如发票识别技能的描述可以这样写用于从图片或PDF中提取发票信息。当用户提供报销单、购物小票或电子发票截图时调用此技能获取结构化数据。输入条件部分要给出触发的最低要求。如果用户只说“帮我报销”但没给图片这个技能就不该被调用。所以加上一句“缺少原始图片或文件时不要调用此技能先请用户提供”。禁忌部分是我后来才加上的效果却出奇地好。每个技能我尽量想清楚哪些场景它绝不能做写死在描述里。比如费用校验技能就注明“本技能仅适用于员工日常报销不含差旅预订差旅相关费用需走差旅管理模块”。写法上还有一个细节描述不要出现过多同义词替换。实测下来用词统一反而能让模型更稳定地触发匹配。有些开发者为了SEO式地优化描述把“报销”写成“费用申请”“支出申报”“财务报销”结果模型在边界场景里就开始飘了。技能描述是工程文档不是营销文案用户怎么说就怎么写保持直接。2.3 技能要不要带状态纯函数优先原则设计技能时最容易犯的一个错误是顺手把状态管理也塞进去。比如一个“保存用户偏好”的技能内部维护了一个全局变量多个调用之间共享状态。这在单次调试时看不出来问题一旦Agent并发执行多个任务状态就串了。用户改了A偏好B任务读取时拿到的是A的莫名其妙。我的原则是技能默认做成无状态纯函数所有外部依赖通过参数显式传入。如果确实需要跨调用保存数据比如记用户上次查询时间把这个状态存到外部存储数据库、Redis而不是技能内部的全局变量。输入参数里带上上下文ID执行时从存储中按ID读取并更新。这样技能可以随时重放、随时回滚不会因为状态残留产生脏数据。3. 从0到1实现一个完整技能的实操记录理论说了一堆拿一个具体例子走完整流程。我选一个大家日常都需要的场景整理会议纪要。需求描述一下给一段杂乱的中文会议语音转写文本输出一份结构化的会议纪要包含讨论主题、关键决定、待办事项与负责人、下次会议时间等。这个技能的开发过程能够覆盖我在前面提到的全部设计要点。3.1 需求拆解与技能边界确认第一步不是写代码而是把需求边界划清楚。会议纪要整理这个需求看似简单里面的坑不少。我需要明确几个问题输入是纯文本还是音频文件如果输入是音频文件需要先去调用一个语音转写技能这不是本技能该做的事。我明确本技能的输入是“语音转写后的文本”。输出格式是固定模板还是自由段落我采用固定模板因为后续可能接入其他系统比如同步到项目管理工具固定结构更利于程序化处理。是否需要支持中文以外的语言首版只支持中文描述里明确说明“不支持英文及其他语种不要强行翻译”。会议纪要的“待办事项”需要负责人如果原文没提到负责人怎么办不编造标记为“未指定”。把边界想清楚之后技能的输入和输出Schema就呼之欲出了。我先把技能文件结构搭起来skills/meeting_minutes/ ├── MY.md ├── schema.json └── main.py各文件用途说明一下。MY.md是这个技能给模型看的“说明书”相当于技能的身份证和使用指南schema.json定义输入输出契约main.py是实际执行逻辑接收schema校验后的参数返回格式化结果。这样每个技能都可以独立测试、独立发布。3.2 技能的三个关键文件到底写成什么样先看MY.md这是模型决定是否调用本技能的依据我用的是前面说的三段式写法# 会议纪要整理技能 用于将一段中文会议语音转写文本整理为结构化会议纪要。 ## 适用场景 - 用户提供会议录音转写文本纯文本希望得到清晰的会议结论 - 输入文本包含讨论过程、决定、待办事项等混杂内容 ## 输出格式 - markdown格式的结构化纪要包含会议主题、参会角色、关键讨论点、决定事项、待办事项含负责人与截止时间、下次会议建议 ## 禁忌 - 输入为音频文件时不要调用应先进行语音转写 - 输入为非中文文本时不要调用不要强行翻译 - 原文没有明确提到的信息如负责人、时间不要编造统一标记为“未指定”接下来是schema.json。这里定义技能接收的输入参数和返回的结果结构{ name: meeting_minutes, description: 从中文会议转写文本中提取结构化会议纪要, input_schema: { type: object, properties: { raw_text: { type: string, description: 会议语音转写文本支持中文, minLength: 20 }, meeting_title: { type: string, description: 会议名称可为空为空时根据内容自动生成, maxLength: 50 } }, required: [raw_text] }, output_schema: { type: object, properties: { success: { type: boolean }, summary: { type: object, properties: { meeting_title: { type: string }, key_points: { type: array, items: { type: string } }, decisions: { type: array, items: { type: string } }, action_items: { type: array, items: { type: object, properties: { task: { type: string }, assignee: { type: string }, due_date: { type: string } } } } } } } } }main.py是核心执行逻辑。在这个例子里我用一个大模型调用来完成从“杂乱文本”到“结构化数据”的转换。但要注意这里的Agent框架调用和技能本身的执行是两个层面技能内部的模型调用是“该技能自己的实现细节”而不是整个Agent在做决策。这样设计的好处是即便将来我们换了底层大模型或者改成规则模型混合方式技能对外的输入输出契约不用变。main.py的核心结构如下import json from typing import Dict, Any def execute(inputs: Dict[str, Any]) - Dict[str, Any]: raw_text inputs.get(raw_text, ).strip() meeting_title inputs.get(meeting_title, ).strip() if len(raw_text) 20: return {success: False, error: raw_text length too short} # 调用内部大模型做结构化提取 # 这里省略实际请求代码关键点在于prompt工程 result llm_extract(raw_text, meeting_title) # 对结果做后处理必填字段缺失时补未指定 for item in result.get(action_items, []): item.setdefault(assignee, 未指定) item.setdefault(due_date, 未指定) return {success: True, summary: result}这里有一个容易被忽略的点从模型拿到的原始输出往往结构不稳定比如JSON里某个字段缺了、数组格式不对。因此每个技能执行逻辑里必须有一个“结果规整”的步骤把模型的自由输出强行归一到schema定义的结构内。我的做法是对关键字段逐个做校验和兜底赋值宁可多写几行也比下游解析报错强。3.3 接入和验证三步走逐个环节确认技能写完之后不要急着整套上。我的习惯是先做三个层级的验证每一层通过再进下一层。第一层验证技能描述是否能被模型正确理解。把MY.md放到一个空的Agent里随机给若干条用户消息观察模型是否在“应该调用”的场景选择本技能、在“禁止调用”的场景不触发。这步可以自动化跑一批模拟对话但至少前两轮建议人工过一下。第二层验证Schema是否能被正确解析。这一步最容易出错的是参数类型。比如raw_text我用string类型长度限制minLength20但如果模型传了个空字符串框架应该返回校验失败而不是继续执行。这里我建议在入口处再写一道防御校验不依赖框架自带逻辑。第三层验证执行结果能否被下游使用。输出是给下游消费者用的不只是给模型看的。我在这一步会单独写一个小的消费者脚本把技能输出直接喂给后续流程比如自动同步到日历或项目管理工具确认格式真正兼容而不是肉眼看个大概。以下是这三步的清单式整理步骤一角色行为测试——确认描述触发准确不出现乱调用步骤二入参出参校验——边界输入空文本、超长文本、缺字段是否稳定返回错误而非崩溃步骤三端到端消费测试——输出结果能被下游系统直接消费并展示正确三步跑通这个技能才算“能用”。很多团队省掉了步骤一和步骤三导致技能本身逻辑没问题但模型就是不按预期调用或者输出格式跟下游不匹配这种问题排查起来最费时间。我在实际项目中把这三个步骤写成了一套本地脚本每次新增或修改技能都跑一遍省了大量联调时间。4. 从单技能到技能编排复杂任务的组合方法单个技能解决的是“一个动作”但真实业务里Agent要完成的往往是一连串动作。比如“帮我处理今天的报销”先识别发票再校验金额再填入报销单最后发通知。这就是技能编排。这个环节处理得好不好直接决定Agent在复杂任务中的可用性。4.1 编排的三种基本模式技能编排跟写程序的控制流其实是同构的核心就三种模式顺序执行、条件分支、循环处理。顺序执行是最常见的。一个技能的输出直接作为下一个技能的输入。典型场景是报销发票识别输出结构化发票字段费用校验技能读取字段按规则判断是否合规输出的结论再交给报销单生成技能。每个环节之间通过一个“数据总线”传递JSON对象。我这里建议把中间数据都打日志出问题方便回放。条件分支用于“根据情况走不同路径”。比如会议纪要技能输出的action_items里如果某个任务标记了due_date就走“创建日历提醒”分支如果due_date缺失就走“待补充”分支或者直接生成一条追办消息。条件分支的实现可以在Agent的路由逻辑里写if/elif也可以用模型来做决策。我的经验是能写死就写死模型判定的稳定性在关键业务路径上不够用。只有真正无法预先枚举的情况才让模型判断。循环处理用于批量场景。比如一次整理10天内的所有会议纪要——先循环调用会议纪要整理技能处理每一天的文本再把结果合并成一份周报。循环要注意两个坑一是技能调用的错误处理某一天的数据处理失败了不能中断整个循环二是总量控制单次Agent任务里技能调用次数要做上限防止死循环或者费用失控。4.2 复用第三方技能库安全与适配经验技能化做起来之后很快就有团队把内部技能沉淀成共享库社区里也出现了一批开源技能集合。复用别人的技能能省不少时间但不是直接拷进仓库就完了。我自己的检查清单包括这么几项。第一看描述和schema是否匹配。有些第三方技能的MY.md描述很强schema却很简陋实际调用会发现模型老传错参。遇到这种情况宁可自己改造schema再上别图省事。第二看执行逻辑有没有隐藏的副作用。检查代码里是否访问了环境变量、是否有网络请求、是否有写操作。如果某个技能内部偷偷调了一个外部API、还带了硬编码的token这本身就是安全隐患。我在审查第三方技能时直接搜索代码中的token、password、api_key等关键词发现一个踢掉一个。第三限定执行权限。Agent在执行技能时建议跑在受限环境里比如容器内无root权限、网络访问走白名单、磁盘写入限指定目录。这个建议在早期项目里容易被忽略等真正出了问题比如技能误删了文件就来不及了。权限收紧 日志留存双管齐下。4.3 版本管理与技能演进技能是有生命周期的。业务规则变了比如报销额度调整、底层模型升级提示词效果变化、外部依赖变了API接口更新都要求技能同步迭代。我在这方面的做法参考了普通软件发布的流程但做了简化。每个技能目录里放一个CHANGELOG.md每次修改记录三个东西改了哪个文件、为什么改、影响范围是什么。然后在Agent的路由配置里指定技能版本号例如当前使用v1.3的meeting_minutes没验证过的不直接上生产。这里用版本号的好处是某次业务方反馈“会议纪要突然格式不对了”我能从版本记录里立刻知道上一版和这一版改了什么而不是靠回忆。灰度上线也值得提一句。对于流程类技能发送邮件、写数据库如果改动涉及执行逻辑我会让系统在最初10%的流量里使用新版本观察错误率和调用失败率确认稳定再全量放开。纯文本处理类技能可以放宽但涉及外部动作的技能务必保守。5. 技能开发路上的高频问题与排查实录技能开发是个实践活踩坑在所难免。我把自己在项目里反复遇到的几类问题整理成了一份排查速查表每一条都是真金白银换来的。5.1 模型“无视”技能规则该怎么排查最让人头疼的问题技能描述明明写得清清楚楚测试用例也跑了模型在某些输入下就是不调用该调用的技能或者调用时传参完全不合理。遇到这类问题我会按顺序排查四个环节。首先检查描述和Schema是否冲突。比如描述里说“必须提供用户ID”但Schema里没有user_id字段模型自然无所适从。其次检查技能数量Agent身上挂的技能太多超过15个时模型的选择准确率会显著下降表现为“漏调”。第三检查输入历史模型的调用决策受上下文长度影响当对话历史太长前面的技能描述被截断或权重降低也会导致漏调。最后检查模型参数设定——温度是否设得过高tool_choice是否被误设为none这两个参数改动对调用行为影响极大。实际排查案例我有一次遇到“费用校验技能死活不被调用”日志显示Agent直接跳过校验去生成报销单了。查了一圈最后发现是技能列表里有个新加的技能描述里包含了“校验”字样模型混淆了两个技能。解决方式是在费用校验技能的描述里加上一句“本技能是所有报销流程的必经环节在生成报销单之前必须调用”问题立刻缓解。这个经验告诉我技能描述的互斥性要显式声明模型才不会搞混。5.2 技能超时、重试与幂等设计的实操经验外部API调用类技能超时和重试是必答题。最简单的实现是设一个超时时间我常用10秒作为上限超时后重试。但如果重试策略不对可能引发更严重的问题——重复扣款、重复发送。幂等设计的核心思路每次任务生成一个唯一的request_id技能在执行外部写入操作前先检查这个request_id是否已处理过。比如发送邮件技能执行逻辑先查数据库是否存在该request_id对应的发送记录有就直接返回上次结果没有才真正发信。这个模式实现成本不高却能消除大半因重试导致的脏数据问题。重试次数方面也要克制。我的经验是外部API最多重试2次第一次等待1秒第二次等待3秒再失败就返回错误信息让Agent换个策略。无限重试只会让系统在外部服务故障时陷入无意义的等待。另外强烈建议给技能的执行时间加上总的超时熔断某些技能陷入了死循环靠外部的熔断机制才能兜底。5.3 技能冲突、命名空间与数据隔离技能数量上来之后冲突问题会浮出水面。最常见的是同名参数不同含义。比如邮件发送技能和消息通知技能都有一个to字段一个是收件地址一个是接收人ID模型传参时容易搞混。我的处理方式是给每个技能的参数加技能名前缀比如email_to和notify_recipient从命名上杜绝交叉。数据隔离则要关注多用户场景。Agent可能同时服务多个用户技能执行时如果不能确保数据按用户隔离就会出现严重事故。我的做法是在技能入口传入一个context对象里面包含user_id和session_id执行逻辑所有数据读写都挂在user_id维度下。严禁在技能内部使用无标识的全局缓存。这几个问题罗列出来不复杂但每一条背后都有排查数小时的代价。我把它们写成了一张速查表放在团队的技能开发规范文档里新成员做技能开发前先过一遍能少走很多弯路。个人最大的感受是技能库的成熟度不取决于技能数量多少而取决于每个技能的设计是否克制、边界是否清晰。与其塞进去100个含糊的技能不如先打磨好20个经得起测试的技能。测试用例、版本记录、权限隔离这些工程手段才是让Agent从“玩具”变成“工具”的真正的分水岭。最后分享一个小习惯每写完一个技能我都会手动构造几个“边界刁钻”的输入跑一遍比如超长文本、纯符号输入、完全无关的内容。这些边界用例往往比正常用例更能暴露问题做多了你会发现技能系统的稳定性就是这样一点一点磨出来的。