1. 为什么这个时代需要“agent-skills”过去一年多圈子里聊的从“大模型能做什么”慢慢变成了“大模型怎么稳定地做成一件事”。如果你亲手搭过Agent多半遇到过这种尴尬模型很聪明但一到具体动作就飘要不就是调工具时漏参数要不就是步骤一多就开始瞎编。解决思路有很多其中最让我觉得接近“根治”的是“agent-skills”这套思路——它本质上不是给模型灌更多知识而是把“做事的方法”沉淀成一套可复用、可组合的技能库。“agent-skills”这个名字我第一次看到时第一反应是“这不就是把Prompt模板换了个说法吗”。后来自己动手整理才发现差得远了。Prompt模板是给模型念的“台词”而agent-skills更像给Agent装配的“肌肉记忆”它包含任务的触发条件、执行步骤、依赖工具、输入输出的约束甚至失败后的回退方案。简单说一个没有skills的Agent是个聪明但没经验的实习生而有了skills之后它才像一个按SOP办事、知道边界在哪的老员工。这篇文章想聊的就是我在实际项目里使用、设计、踩坑之后总结出的agent-skills落地经验。适合正在做Agent应用、想提升模型执行稳定性、或者准备搭建内部Agent平台的人参考。我会尽量少讲虚的多放能直接用的结构、代码和判断标准。你把这套东西拿回去不需要改模型、不需要上多贵的算力先把技能库搭起来Agent的可用性能上一个台阶。我自己的体会是Agent系统里模型能力决定上限但技能体系决定下限。只要下限够稳产品就敢对外开放这也是我后来把所有实验性Agent都重构出一层skills层的原因。下面我会从设计思路、技能结构、实操代码、评测方法、常见坑五个方面展开带你完整走一遍。2. agent-skills究竟是什么从工具调用到技能编排2.1 先分清工具、技能、任务三者的层次为了不把概念搞混先给一套我常用的分层方式。工具Tool是最底层的能力单元比如“查天气”“发HTTP请求”“计算MD5”它是单一的、原子的没有业务判断。任务Task是用户发出的一句话诉求比如“帮我安排明天下午三点的会议”它往往是模糊的、需要拆解的。而技能Skill正好卡在中间它把多个工具串起来加上判断逻辑、默认参数、异常处理形成一套可以重复执行的能力。举个例子。你有一个“发送会议邀请”的工具入参是参会人、时间、会议室ID。但直接让模型调这个工具它很容易漏掉“会议冲突检测”“跨时区换算”这种潜规则。而如果你封装出一个“会议安排技能”这个技能内部定义了完整的执行链先查忙闲、再选会议室、时区不一致时统一转成参会人本地时间、最后才发邀请并做结果校验。模型只需要说“我想开会”技能层就会自动完成剩下的动作。这就是agent-skills的核心价值之一把“怎么做”从模型的不稳定推理中剥离出来变成确定性代码或半确定性的流程编排。既然模型在自由发挥时容易出岔子那就尽量压缩它自由发挥的空间只让它负责“理解意图”和“选择技能”而技能内部的路径是固定的、经过测试的。一层层往下收系统的整体可靠性自然会上升。2.2 为什么现阶段的Agent离不开技能库我见过不少团队早期方案是给模型配十几个工具然后靠Prompt去约束“你先做A、再做B”。一开始demo效果很惊艳一到真实流量就露馅。核心原因是模型对工具的调用受到上下文长度、注意力漂移、甚至Prompt位置的影响步骤越多中途出错概率越大。技能库的另一个价值是沉淀经验。比如客服域里“处理退款申请”这件事包含验证订单、核对金额、确认支付渠道、发审批通知等七八个环节每个环节都有业务规则和边界条件。如果没有技能库这些规则只能散落在Prompt里改一处就要重新调整个Prompt风险很大。而把它们固化成一个Skill后续不管是换模型还是换工具实现只需要改技能内部代码对外接口完全不变。还有个容易被忽视的好处——可测试性。Prompt怎么测最多做几个case看回复质量。但技能是可以做单元测试的给固定的输入看输出是否符合预期、边界条件是否被正确处理、异常分支是否走到兜底逻辑。有了这层测试保障Agent系统的回归成本大大降低。这也是我后来坚持在项目里引入skills层的最重要原因不是为了架构好看而是为了让系统真的能迭代、能收敛、能上线。2.3 技能编排与编排器的关系很多框架已经在做“路由”和“编排”比如LangChain里的Router或者各种Agent框架里的Planner。我的看法是编排器负责“决策”技能库负责“执行”。编排器根据用户意图决定调用哪个技能、按什么顺序组合技能技能内部则是相对封闭的执行单元不关心上游是怎么选的。这里容易踩一个坑把技能编排逻辑全部写死在编排器里。比如在代码里if user_input包含“退款”就走退款技能这样短期可行但技能一多编排器就变成一堆屎山。更合理的做法是给每个技能声明自己的触发条件和能力描述让编排器通过推理或匹配来完成路由。这样新加技能时不用动编排器只注册技能描述就行。我自己项目的做法是给每个技能写一段不超过80字的描述包含“解决什么问题、适合什么场景、需要哪些关键参数、不适用什么情况”。然后让模型读全部技能描述结合用户输入选技能。一开始担心模型选错实际跑下来发现只要描述写得清楚准确率能做到90%以上。剩下的模糊case再配合一个“确认追问”机制兜底。3. 搭建一套技能库的完整设计思路3.1 从业务场景倒推技能清单动手写代码之前先把技能清单列出来。我推荐的方法叫“场景故事法”找3到5个真实用户故事模拟完整的交互流程每走到一个需要外部能力或确定逻辑的节点就记录一个技能候选。比如做一个人力资源问答Agent场景可能是“员工问年假还剩几天”那对应的技能就是“查询年假余额”和“计算年假折算”场景也可能是“发起调薪申请”那技能就得包含“构造调薪流程工单”。清单列完之后做一个合并和裁剪。原则是一个技能只做一件完整的事。不要造出那种“万能技能”入参七八个、内部几十个分支那样既难维护也让模型很难判断什么场景该选它。宁可把复合流程拆成三个小技能然后在编排层通过顺序组合来完成。比如“入职办理”拆成“创建员工档案”“分配默认权限”“发送欢迎邮件”三个技能编排器按顺序调度。裁剪的时候还要考虑技能的复用频次。如果一个技能只被一个场景用到而且逻辑不复杂可以先不封装直接在流程里写条件分支。技能库的精髓是“高复用、低耦合”不要为了封装而封装。3.2 技能模板描述、入参、执行体、兜底策略不管用什么语言或框架我建议每个技能都按四个模块来组织描述description、参数定义parameters、执行体executor、兜底策略fallback。这四个模块缺一不可。描述是给编排器或模型看的不是给人看的。所以必须写得“对机器友好”说清楚触发条件、适用场景、有什么限制。写描述有个技巧多写反例。比如“此技能仅在用户主动询问余额时使用不要在其他查询场景使用”这样能显著降低模型误调用的概率。参数定义最好用JSON Schema不要用松散的口语描述。JSON Schema能约束类型、必填项、枚举值模型生成入参的时候不容易漏字段。我之前遇到过Agent死活不传“申请日期”的情况后来在Schema里把format写上、把必填标出来问题立刻好了很多。执行体是技能的核心一般封装成函数或类。要注意的是执行体不应该包含复杂的交互式对话逻辑它的职责是“完成动作并返回结果”。判断标准很简单如果一个技能内部还要跟用户来回确认好几轮说明它不是技能而是流程应该拆开。兜底策略是最容易被忽略却最重要的模块。技能执行失败时返回一个友好且可理解的错误结构包含错误码、可读信息、可执行建议。这样编排器才能根据错误码决定是重试、换技能还是转人工。3.3 技能的状态管理与依赖处理如果一个技能是纯函数式的无内部状态那是最理想的。但现实业务里很多技能需要依赖上下文。比如“发送周报”技能需要知道本周完成的任务列表这个数据来自上游的“任务汇总”技能。处理这种依赖我推荐在编排器层面显式传递而不要让技能自己去找上下文。具体做法是维护一个上下文对象编排器每执行完一个技能就把结果写入上下文。后续技能通过参数引用上下文里已有的字段。这样做的好处是每个技能还是无状态的测试时可以直接mock输入编排器则负责串联数据流。还有一类依赖是外部环境依赖比如某个技能需要调用内部API而内部API的鉴权方式、超时时间、重试策略各不相同。我的经验是把这些依赖收敛到技能内部技能对外只暴露业务级参数。这样上层不需要关心某个技能走的是HTTP还是RPC也不需要在编排层散落各种鉴权代码。4. 实操从0到1把技能逻辑跑起来的完整过程4.1 技术选型从轻量脚本到框架化说到技术选型先给一个结论技能库不一定非要上重型框架根据团队规模和系统复杂度来选。如果你只是个人项目或者在做概念验证最简单的方案是用Python写几个函数配上统一的装饰器注册再写一个几十行的路由模块。伪代码大概长这样SKILL_REGISTRY {} def skill(name, description, parameters_schema): def decorator(func): SKILL_REGISTRY[name] { name: name, description: description, parameters_schema: parameters_schema, func: func, } return func return decorator skill( namecalculate_leave_balance, description计算员工年假余额仅在用户查询年假时使用, parameters_schema{ type: object, properties: { employee_id: {type: string}, year: {type: integer}, }, required: [employee_id], }, ) def calculate_leave_balance(employee_id, yearNone): # 这里写真实逻辑 ...这个方案的好处是透明、可控、没有框架绑架适合快速迭代。坏处是技能多了以后调度、并发、缓存、监控都需要自己处理。如果团队已经有Agent框架基础或者技能数量超过二十个建议做一层统一抽象。可以选开源的Agent框架作为底座把技能以插件形式接入。我比较看重的框架能力有四个技能版本管理、技能热更新、调用链追踪、灰度发布。前两个提升开发效率后两个保证线上稳定。4.2 一个真实技能从定义到上线的完整流程拿“周报自动生成”技能来走一遍完整流程这样更有体感。第一步定义技能描述。这个技能解决什么问题它接收“本周任务明细”和“下周计划”输出一段格式化周报文本。描述可以这样写“根据任务明细生成周报适合用户要求汇总本周工作内容、生成周报、汇报进展时使用。此技能不包含任务查询能力需要先通过任务查询技能获取本周任务列表。仅处理周报文本生成不负责发送邮件或提交到系统。”第二步定义参数Schema。必须包含哪些字段task_items是数组每个元素里有title、status、completion_ratenext_week_plans是字符串数组。为了兼容不同上游我把task_items设成必填next_week_plans设成选填。第三步实现执行体。这一步相对简单就是纯文本模板拼接加上一点数据校验。关键点在于如果task_items为空要返回一个特定的错误码而不是输出一份空洞的周报。因为如果周报内容太虚用户一眼就能看出来是机器生成的信任度会大打折扣。第四步注册到技能库并在编排器里写一条样例路径。比如用户说“帮我生成一下这周的周报”编排器先路由到“任务查询技能”拿到task_items再路由到“周报生成技能”最后把文本返回给用户。整个流程下来我最大的体会是描述和Schema的打磨时间应该占整体开发时间的一半以上。代码本身不难写难的是让编排器在成千上万种用户表达中准确选中这个技能并且保证入参不缺不漏。4.3 与主流Agent框架的集成方式现在很多框架都支持自定义工具或者技能。集成时有几个注意点。第一是命名不要冲突。技能库的命名空间建议用“域_动作”的格式比如“hr_query_balance”“hr_create_workflow”“wiki_search_page”。命名冲突轻则路由混乱重则技能被随机覆盖特别隐蔽。第二是错误信息要标准。框架在技能报错时通常会把错误信息塞给模型让模型自己决定怎么回复。所以技能返回的错误不能是“Exception: xxx”而应该是结构化字段error_code、message、suggestion。这样模型能看懂代码也能处理。第三是异步问题。很多真实技能涉及外部调用必须用异步方式执行。如果你的框架不天然支持异步技能建议自己在技能内部做并发控制不要让一个慢技能阻塞整个编排。我实际项目里做过一个粗略统计引入技能库后Agent端到端任务成功率从62%提到了81%。提升来源主要是两部分一是技能内部固定逻辑减少了模型胡编的概率二是错误能结构化返回后很多失败场景可以自动重试或转人工而不是直接对话中断。5. 技能评测怎么做量化指标与回归体系5.1 评测维度准确率、召回率、稳定性、延迟技能库上线之后怎么证明自己做的不是自嗨我的建议是建立一套四维评测指标。第一维是路由准确率即编排器把用户请求分到正确技能的比例。第二维是执行成功率即技能被调用后内部逻辑能跑通、返回业务成功结果的比例。第三维是结果稳定性同一输入在相同条件下多次执行输出是否一致。第四维是端到端延迟从用户发起到收到最终结果的时间。前两个指标其实是两回事。路由准确率关注“选没选对”执行成功率关注“做没做成”。我见过很多项目的Agent能选对技能但执行老失败也见过技能本身没问题但路由老选错的情况。分开测才容易定位问题。稳定性这个指标最容易忽略。模型有随机性但同一个技能应该尽量保证确定性。如果同一个技能跑五次三次返回不同的结果用户就会觉得“这东西不靠谱”。所以我在技能内部尽量用代码逻辑而不是模型生成来输出最终结果只在极少数需要总结归纳的场景才让模型参与。5.2 搭建一套技能回归测试集技能库要敢迭代必须有回归测试集撑着。我的做法是维护一个“skill_test.json”文件里面按技能组织测试用例。每个用例包含用户输入或参数、期望路由的技能名、期望结果可以用匹配器做模糊对比、允许的错误码列表以及备注说明为什么写这个case。测试集里至少要包含四类case正常路径case、边界case、易混淆case和失败兜底case。正常路径是标准输入边界case用来测空值、极长文本、异常格式易混淆case是用来测路由的比如“帮我算算我今年还剩几天年假”和“帮我看看我这两年都休了多少天年假”看似相关其实分别应该路由到“余额查询”和“休假记录查询”失败兜底case则验证技能在外部依赖异常时是否能返回结构化错误。回归测试可以做成定时任务每次发版都跑。跑完看两个维度有没有新引入的失败case以及之前失败的case是否被修复。不要求百分百通过率但趋势必须是收敛的。如果某个技能的失败case连续几次都在增加就应该暂停该技能的使用先排查再说。5.3 评测结果如何反馈到技能优化评测不是为了得一个分数而是为了指导下一步动作。我的优化路径一般是先看路由准确率低就先改技能描述和反例实在不行再调整编排策略再看执行成功率低就查技能内部逻辑、外部依赖和参数Schema最后看延迟慢就做并发、做缓存、或者在技能内部加超时熔断。这里分享一个踩过的坑有个技能路由准确率一直高但执行成功率低。查了很久才发现是技能内部调的API有频率限制并发一高就返回限流。后来在技能内部加了本地缓存和降级逻辑成功率一下就上来了。这个问题从评测指标上能看出来但如果没有评测体系光靠看日志找出根因会慢非常多。6. 常见问题与排查技巧实录6.1 Agent不调用技能或者用错技能这是最高频的问题。模型放着好好的技能不用自己在那儿“凭空回答”。我的排查顺序是这样先看技能描述是不是写得太泛导致模型不觉得它专业再看技能描述里是不是缺少“什么时候用”的触发条件最后看模型对多个技能描述是不是产生了混淆。如果描述已经很明确还是不调用那就要检查你的编排器。有些编排器是先把用户输入做意图分类再按分类映射到技能。如果意图分类本身不够细技能就永远不被选中。这时候与其反复调Prompt不如在编排器里加一个“路由置信度”阈值低于阈值时向用户反问“你是想查余额还是看记录?”还有一个特殊情况模型调用了技能但传的参数不对。常见原因用上了错误的字段名或者格式不对。我的建议是在JSON Schema里不要只写字段名最好每个字段给一个中文注释说明含义再给一两个示例值。模型看到示例后参数生成的准确率会明显提升。6.2 技能执行成功但结果不满意技能“做成功了”但用户不满意这种问题最让人头疼。先确定一个原则技能的成功定义不是“跑通代码”而是“解决用户问题”。所以返回结果一定要有用户视角的校验。我之前做过一个订会议室技能代码逻辑完全正确会议室也订上了但用户就是觉得体验差。后来仔细分析才发现技能返回的是“会议室已预订会议ID为12345”但用户当时想知道的是“是否和老板的会冲突”。你返回了结果却没法打消用户的疑虑。解决办法是在技能内增加一个“关联信息查询”的可选参数当用户提到“冲突”时自动附带查询相关日程并做出提示。类似的案例还很多。核心教训是技能的执行体不应该只关注动作完成状态还要关注“如何呈现结果才能让用户获得完整信息”。一个优秀的技能在返回成功的同时应该把用户关心的上下文也带回来。6.3 技能数量膨胀后编排器怎么扛住技能从几个涨到几十个的时候编排器迟早会遇到性能或准确率问题。因为每次路由都要把几十个技能描述塞进上下文既浪费token又让模型更难做选择。我的解决方案是给技能做“分层路由”。第一层给技能打标签比如“查询类”“写入类”“计算类”“通知类”。先根据用户输入判断大类再在大类内部选择具体技能。这样每次路由只需要面对五六个候选技能准确率和速度都会好很多。第二层是在技能描述里标注“关联技能”当一个技能被选中时把关联技能也带上方便模型做组合调用。还有一个细节描述越长的技能模型越容易记住。但也不要为了排序而可以加长描述因为长描述会稀释关键信息。理想的描述是70到120字之间重点信息前置反例补充在后。6.4 一个排查技巧全链路日志里加技能调用地标Agent系统排查问题最怕的就是黑盒。我的习惯是给每个技能的执行体入口和出口都打上结构化的日志包含技能名、入参、出参、耗时、错误码。这样一个请求从进来到出去日志就形成了一条完整的技能调用链。有一次排查用户投诉“明明让Agent查了金价回复却说没有权限”我看日志发现技能调用链根本没有“金价查询”的记录说明编排器压根没往那个技能路由。于是我把排查重点从前端逻辑挪到路由策略上问题很快定位。所以给技能日志做“地标”比事后猜Agent的随机行为要高效得多。7. 对agent-skills未来的一点个人判断技能库这个方向我判断还有很长一段路可以走。短期内的趋势是技能共享生态团队之间、甚至公司之间把通用的技能封装好像积木一样互相拼装中期来看技能会跟评测体系更深度地绑定没有评测的技能不允许上生产长期来看技能可能不再只是“代码函数”而会包含更复杂的数据飞轮通过调用数据持续优化技能本身的表现。我最近在尝试的方向是把技能库做成“半自动生成”的给出一段示例对话让大模型自动提炼步骤、参数和边界条件生成一个技能草稿再人工审核后进库。这个流程虽然还不够成熟但已经帮我省了不少时间。如果你正在做Agent相关的事我的建议很简单先别急着追模型版本先把技能库这层功夫练扎实。它不性感不热闹但它是把大模型从“玩具”变成“工具”的那道关键工序。我自己的实践反复证明这一点模型进步很重要但更重要的是你用什么方式让模型稳定地解决问题。agent-skills这条路值得认真走。