这两年做AI应用我最大的感受就是大家讨论的重心已经从大模型有多聪明慢慢变成了大模型能帮我干多少活。而决定后者上限的往往不是模型本身而是你给模型配了多少可用的技能——也就是agent-skills。同一个模型配了技能库的agent和只会纯聊天的agent实际用起来完全像两个产品。这篇文章我想结合自己做过的几个项目把agent-skills从概念拆解到落地实现、再到踩坑修复的完整经验梳理一遍希望能给正在做智能体、自动化工作流的同学一些参考。1. agent-skills到底是什么为什么突然这么火1.1 先给个朴素的定义agent-skills直译就是给智能体agent准备的一组能力单元。说人话就是你的AI助手除了会说话还会做事。比如让它查天气、算个税、调接口、发邮件、操作浏览器、生成报表这些都是技能。而agent-skills不是单个技能是这些技能的集合和管理体系包含技能的编写方式、描述规范、调用协议、权限边界以及agent如何发现和选择合适技能的机制。我见过不少人对这个概念的误解以为agent-skills就是把一堆API文档丢给模型就行。实际上远没那么简单。如果只是丢API文档模型确实能知道有这个东西但并不知道什么时候该用它参数该怎么填出错时怎么办。agent-skills要解决的是三个层面的问题模型知不知道有这个能力发现层、模型能不能正确调用执行层、调用失败时怎么恢复容错层。三层都做好才叫合格技能库。1.2 它和function calling、ReAct、MCP的关系做这块绕不开几个概念我先帮大家理清楚不然容易绕晕。function calling函数调用是模型层的能力指模型能在生成回复的同时输出一个结构化的调用指令比如{name: get_weather, arguments: {city: 上海}}。这是agent-skill的底层执行机制之一。ReAct是一种推理模式让模型交替进行Reasoning推理和Acting行动边想边做做完看结果再想下一步。这相当于给agent装了大脑回路很多技能编排都依托这个循环。MCPModel Context Protocol是近期很热的一套开放协议用来统一AI应用连接外部工具和数据源的方式。它解决的是技能如何标准化接入的问题你可以把它理解为USB-C接口而agent-skills里面每一个技能就相当于一个USB设备。不一定要用MCP但用了它技能库的可迁移性会好很多。所以关系大概是这样的agent-skills 技能的内容层技能从哪儿来、怎么描述、怎么组织function calling 技能的调用层模型如何发起调用ReAct 技能的编排层模型如何决定调用顺序MCP 技能的接入层工具如何连进系统1.3 为什么现在是做agent-skills的好时机一个很现实的原因模型API的价格在快速下降但开发模型外围能力的人力成本没降。过去大家拼命调prompt、做RAG本质上是在弥补模型不会动手的短板。而agent-skills把动手能力沉淀成了可复用的资产做一次到处用。另一个原因是应用层的竞争已经进入深水区光靠聊天窗口留不住用户交付成果才是硬道理。我实际测下来给客服机器人配上订单查询、退换货办理、物流跟踪三个技能之后问题解决率从不到三成提升到七成以上这个提升是纯对话层很难做到的。2. 技能库的设计思路别急着写代码先做规划2.1 技能的粒度控制设计技能库第一个要决定的问题是一个技能该有多大。我在项目里的经验是技能粒度要遵守可独立有价值原则。一个技能应该能独立回答一类问题比如查天气订机票而不是笼统的帮助用户出行。但也不要拆得太细比如获取用户输入的城市这种就不该做成技能因为它不是一个完整任务只是流程里的一步。一个实用的判断标准如果某段能力既不会被多个流程复用也不具备独立的用户价值就不该单独成技能。如果一段逻辑你发现两个以上的场景都要用那就值得抽出来。举个例子很多技能都需要做用户身份校验那verify_user就可以是一个通用子技能被其他技能组合使用。2.2 技能描述的重要性被严重低估我可以很负责任地说80%的agent技能调用失败问题不在代码逻辑而在技能描述写得烂。模型不像人会点开你的函数看注释它只能通过你在技能清单里给的描述来判断这个工具是干什么的、什么时候该用。描述写不清楚等于是你给一个实习生发了张字迹潦草的工具说明书他自然不知道该在什么场景拿出什么工具。这边分享几条我总结的描述规则以动词开头写清楚动作对象用获取指定城市的实时天气信息而不是天气。写明适用条件和触发场景比如当用户需要了解未来某天的天气时使用。写清楚不适用的情况比如若用户只问气温趋势请使用get_weather_trend而非get_weather。参数要注明格式要求和取值范围比如date格式必须是YYYY-MM-DD且不得早于今天。加一句副作用提示比如该操作会扣除用户账户余额执行前需确认用户同意。这些看起来是文字工作但实际效果非常明显。我最开始图省事描述写完不到20个字模型经常把get_order_status和get_order_list搞混后来把触发场景和排除情况写清楚之后误用率下降了一大截。2.3 分层基础技能、复合技能、策略技能技能数量少的时候不分层无所谓但当技能超过二三十个模型的选择准确率会明显下降。这时候就要引入分层设计。我是这么分的基础技能atomic skills不可再拆的最小能力单元比如调用某个API、执行一段SQL、读写一个文件。它们直接对资源操作是技能库的最底层。复合技能composite skills编排多个基础技能完成一个完整任务。比如订酒店流程会调用搜索酒店、读取评分、查看用户偏好、提交订单等多个基础技能。策略技能strategy skills这部分抽象程度更高它不是一个具体的动作而是在某个场景下如何决策的推理框架。比如客户投诉处理策略它不直接调用API而是告诉模型先共情再定位问题再给方案超出权限时上报。策略技能往往控制着复合技能的编排方式。分层的价值在于模型先看到的是上层技能清单再根据需要展开下层技能减少了单次决策的选项数量。我看过一些做得极端的方案甚至会在技能描述里主动写如果需要下单请先调用get_shopping_cart查看当前购物车再调用checkout——这就是基础技能之间的行动指引效果可比纯靠模型瞎编排稳得多。2.4 命名规范与技能索引技能多了之后命名混乱问题就凸显了。中文名、英文名混用动词和名词颠倒都会让模型搞糊涂。我建议统一用动词_名词的英文蛇形命名比如get_stock_price、create_calendar_event。技能库里做一层索引按业务域分组比如finance_skill、calendar_skill、crm_skill方便维护者检索也方便模型在按域筛选时找到候选。3. 实操落地从零搭建一套可用的agent-skills体系3.1 技术选型自研协议还是用MCP我建议如果你的技能数量在个位数、只用在一两个流程里先别上重框架写个简单的注册表就够了。框架是用来解决复杂问题的不是用来炫技的过度设计是很多项目马拉松跑不动的原因。如果技能超过二三十个、要跨多个系统调用我建议直接用MCP。理由有几个它能统一工具的接入方式不用给每个服务单独写适配层。标准化之后技能可以跨项目复用甚至可以直接使用社区里现成的MCP服务省不少事。MCP的生态在快速成熟客户端、调试工具、测试工具都越来越顺手。但选择MCP也有成本需要学习和维护协议规范服务端和客户端都要按它的模型来设计。所以别盲目上先评估团队时间成本。3.2 落地一版最简技能运行框架Python示例我这边用一个Python的最小实现来讲核心套路方便大家先跑通流程再考虑加东西。这里做一个简化版技能管理器支持技能注册、清单输出和一个简单执行循环。import json import inspect import re class SkillRegistry: def __init__(self): self._skills {} def register(self, name, description, parameters_schema, handler): self._skills[name] { name: name, description: description, parameters: parameters_schema, handler: handler, } def get_skill_list(self): return [ { name: s[name], description: s[description], parameters: s[parameters], } for s in self._skills.values() ] def execute(self, name, arguments): skill self._skills.get(name) if not skill: raise ValueError(fskill [{name}] not found) return skill[handler](**arguments) # 技能注册示例 async def get_weather(city: str, date: str): # 在实际项目中这里请求天气服务API return {city: city, date: date, condition: sunny, high: 28, low: 18} registry SkillRegistry() registry.register( nameget_weather, description( 获取指定城市在指定日期的天气情况。当用户询问天气、气温、降雨概率、 风力等信息时使用。date格式为YYYY-MM-DD若未给定日期则默认今天。 ), parameters_schema{ type: object, properties: { city: {type: string, description: 城市名称如北京、上海}, date: {type: string, description: 日期YYYY-MM-DD}, }, required: [city, date], }, handlerget_weather, )上面这个注册器看起来不复杂但它已经覆盖了技能的定义、发现和调用三个基本环节。实际项目里我会在这个基础上增加鉴权、审计、缓存和重试。3.3 模型循环调用不要让模型直接焊死技能一个经常被忽略的细节即便注册好了技能也不意味着模型知道什么时候该调、调完之后下一步做什么。这里需要一个循环让模型能看到技能清单 - 决策调用或不调用 - 执行 - 观察结果 - 再决策。简化版的对话循环大致长这样import json from openai import AsyncOpenAI client AsyncOpenAI() async def run_agent(user_message): messages [{role: user, content: user_message}] # system message中加入技能清单 system_message { role: system, content: ( 你是智能助手你可以使用以下工具来帮助用户完成任务。 只有确认用户请求与技能相关时才调用不要滥用工具。\n json.dumps(registry.get_skill_list(), ensure_asciiFalse) ), } messages.insert(0, system_message) for step in range(8): resp await client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolsregistry.tool_schemas_for_openai(), ) msg resp.choices[0].message # 模型没有调用工具结束 if not msg.tool_calls: return msg.content # 执行模型请求的工具调用 tool_outputs [] for tc in msg.tool_calls: # 解析参数 try: args json.loads(tc.function.arguments) result registry.execute(tc.function.name, args) tool_outputs.append({ role: tool, tool_call_id: tc.id, content: json.dumps(result, ensure_asciiFalse), }) except Exception as e: tool_outputs.append({ role: tool, tool_call_id: tc.id, content: json.dumps({error: str(e)}, ensure_asciiFalse), }) # 将模型发起调用的消息和工具结果追加进上下文继续循环 messages.append(msg) messages.extend(tool_outputs) return agent steps exceeded这个循环你看着眼熟本质上是ReAct模式落地。几个值得注意的点循环步数设了一个上限8步防止agent陷入死循环或者无限递归。如果任务较复杂我会把这个值调大但会配合token消耗上限做限制。每次工具调用的异常结果要回灌给模型让它能感知到刚才那个动作失败了然后修参数或换方案。失败信息里尽量带回可读的error message。工具调用的历史消息必须完整保留因为后续步骤需要参考之前的执行结果这里省不得token。3.4 技能的参数Schema怎么设计才不会翻车参数Schema设计是agent-skills里最容易出细节问题的地方新手经常会犯两个错误一是把参数类型写得过于严格比如强行要求Enum但模型根本不知道有哪些枚举值二是string类型的约束太模糊模型不知道该填什么。我给出的实用建议是所有参数都必须写description而且description里要包含示例值。比如city: 城市名称例如北京、上海不要带市字。如果参数有可选值直接用enum写出来不要只靠描述让模型猜。模型在JSON输出里生成enum值比从描述中推理靠谱得多。日期、数字这类参数务必要写格式。比如金额单位为人民币元整数不得大于1000000。不写这些模型经常给你填成带小数点的或者格式不匹配的。允许模型在参数缺少时使用默认值所以在schema里尽量设置好default。比如默认查询当天天气那date字段就不必设为required。3.5 给技能加测试用例技能逻辑要经过验证才算数。我为每个技能都写了个测试用例主要覆盖三块功能测试给定合法参数技能是否正确执行。容错测试给缺参数、错格式参数技能是否返回合理错误而非崩溃。模型选择测试给一段用户意图文本看模型是否选择了正确技能。这一步是很多团队容易漏掉的却是我认为最关键的。模型选择技能不准确技能写得再好也白搭。用一批标注过的用户话术做回归测试能让你在升级模型或改技能描述时心里有底。4. 实操中踩过的坑六类高发问题排查实录4.1 模型死活不调用技能现象请求都已经命中技能了模型还在用我的知识库无法获取实时信息这样的套话回复就是不触发function calling。排查路径先确认技能清单是不是真的传进了请求里。很多时候是消息结构拼错了工具信息没放进session。再看技能描述是不是有尽量别用工具的消极语言。我见过团队在描述里写仅在万不得已时调用把这个去掉之后调用率立马上来了。还有一种是描述里给了过强的判断条件比如如果需要技能则调用否则不调用模型会在犹豫中倾向于不调。要让描述尽量明确不要留给模型太多自由裁量空间。4.2 模型选择了错误技能现象用户问我的订单到哪儿了模型调了get_order_list而不是get_order_status。常见原因两个技能描述边界不清晰。解决方式不是改代码而是改描述在get_order_list的描述里加一句仅当用户需要查看多个订单时使用在get_order_status的描述里加用于查询单个订单的实时物流或处理进度。做过几组对比之后你会发现描述里给例子是提升选择准确率的最有效方法之一。4.3 参数解析报错现象模型生成的arguments不满足JSON格式或者字段类型对不上调用直接失败。这个我见过太多次了。几个应对措施解析arguments时一定用try-catch解析失败时把原始字符串塞回给模型让它自己重新生成不要直接崩溃。在system message里附加一段参数生成规范比如所有字段值必须是字符串、数字或布尔值不允许传对象嵌套除非schema明确要求。如果用的是OpenAI可以在tool schema里严格设置additionalProperties: false这样能避免模型多填未知字段。实测下来能减少不少解析问题。4.4 agent陷入无限循环现象模型反复调用同一个技能或者几个技能来回调就是不产出最终结果。原因通常有两个一是循环上限没设二是技能调用的返回数据不够可决策。比如get_weather返回了一个完整JSON对象模型发现有大量字段可以处理就反复去查询不同字段。解决方式限制循环步数明确告诉模型你最好在X步内完成。在工具返回的内容里主动放一句summary把关键信息提炼出来降低模型处理成本。同时还可以在system提示里写如果工具返回结果已经足够回答用户问题请直接给出最终回复不得再次调用工具。4.5 权限和副作用失控现象一个仅查询的agent居然调用了删除接口。这种事故一旦发生责任是无法用模型幻觉来搪塞的。技能权限边界必须在框架层强制不能依赖模型自觉。我自己的经验是在执行器executor层做白名单校验某些技能只有特定角色可用与当前会话身份不匹配就拒绝执行。对副作用技能创建、修改、删除、转账、下单必须加一个用户二次确认环节。模型可以发起意向但真正的写操作要由用户在对话里明确确认后框架才真正调用。审计日志不能省。每次工具调用都必须记录调用了什么技能、参数是什么、发起时的上下文摘要、执行结果、耗时、花费token数。不然出了事你连复盘的数据都找不到。4.6 技能库变大之后性能跟不上现象技能数量超过50个每次请求把全部技能描述塞进上下文token费飙涨调用延迟也上去了。解决思路是给技能做检索召回而不是全量加载。可以先把技能按语义embedding每次请求先根据用户意图召回top 5~10个相关技能再把这部分技能清单传给模型。这样既保证了模型能看到候选又降低了每次对话消耗的token量。还有一种做法做两级路由。第一级用分类模型判断用户意图属于哪个技能域第二级在指定域的技能子集里让模型选。这个方案的稳定性和召回率我都测过效果不错但更依赖你对业务域的划分质量。5. agent-skills能做多深进阶经验与扩展思考5.1 技能编排比单个技能能力更重要技能库发展到一定程度瓶颈不再是有没有这个技能而是怎么让一堆技能配合完成复杂任务。这就要引入流程编排workflow orchestration。我的做法是给复合技能定义一套执行计划明确每一步该调什么技能、如何校验结果、何时回退到用户确认。比如处理退款这个复合技能执行步骤是先验证用户身份再查订单归属再校验退款条件最后调用退款接口并发送通知。每一步的结果都是下一步的输入任何一步失败都要反馈给用户并停止流程而不是盲目往下走。这种编排设计比单纯靠模型自由发挥要可靠得多毕竟可预见的业务场景应该用确定性流程解决把不确定性留给模型做兜底。5.2 跨Agent共享技能库当系统里有多个不同角色的agent比如客服、导购、售后它们往往需要一些相同的技能但也有各自专属的技能。我建议技能库做共享私有两层底层的原子技能全共享上层按角色分组挂不同可用的复合技能。这样改一个底层技能就能惠及所有agent不至于在几个地方重复维护同一段逻辑。5.3 技能使用数据复盘最后给一个我坚持了很久的习惯定期复盘agent的技能调用数据。看哪些技能高频调用哪些技能从来没被触发过哪些技能虽然被触发但频繁失败。这个数据直接指导下一轮优化。如果一个技能上线三个月调用量为零那大概率是描述有问题或者这个技能本身就没有被用户需要该砍就砍。技能库里少而精永远好过多而杂。每加一个技能都在增加模型的选择成本所以加技能要克制要做减法比做加法更体现功力。6. 关于agent-skills的几点个人体会做agent-skills做了几个项目之后我最大的感悟是这活儿七分是工程思维三分是模型理解。很多团队一上来就死磕提示词或者堆模型能力但真正拉开差距的其实是那些笨功夫——技能清单写得好不好、描述边界清不清晰、异常处理完不完整、审计日志全不全。这些没有特别高深的技术但每个设计决策都在影响最终体验。如果你现在正准备给自己的agent配技能库我建议先从一个小场景开始挑三个高频任务把这三个任务的技能做深做透。先跑通模型看到技能清单 - 正确调用 - 拿到结果 - 正常收尾的最小闭环再逐步扩充。这个过程中你会积累不少对模型行为的直觉之后再上规模就不容易翻车。另外平时多关注MCP这类标准化协议的进展很有可能未来agent-skills会像今天的接口文档一样标准化届时跨项目、跨团队的技能复用会容易得多。在这个趋势到来之前先把你自己技能库的组织和积累做好等那天真来了你的资产就是最大的竞争力。