你最开始看到“agent-skills”这个词如果只觉得它是在讲“给大模型写几个函数去调用”那就把它想简单了。我最早也是这么理解的直到自己动手维护一套几十个技能模块的智能体才发现真正难的不是写代码而是设计出一套能让模型稳定理解、正确触达、出错还能自己绕回来的技能体系。这里面有描述工程的讲究有参数规范的设计有编排和回退的博弈还有一堆只有跑过真实场景才会撞上的坑。这篇就把我在实际项目里总结下来的思路、踩坑记录和可复用的做法完整分享出来。它适合谁看如果你已经在做智能体开发不管是基于开源编排框架还是自建调用循环都会用到“技能”这个概念。如果你刚开始接触正准备给一个简单助手加工具能力这篇能帮你少走弯路直接搭出一个能持续扩展、不容易翻车的技能骨架。1. 从一句需求到一套技能树1.1 技能与普通函数的边界先捋概念。一个普通的函数输入参数、执行逻辑、返回结果这套流程你自己完全控制。但“技能”不一样的地方在于它是由大模型在对话过程中动态决定要不要调用的模型负责解析用户意图、填充参数、触发执行。这个角色反转意味着你写的每一行描述、每一个参数约束其实都是在跟一个“理解能力有限、偶尔还会自作主张”的合作者沟通。举个我自己的例子。最开始我把一个“查天气”的功能直接注册成技能函数签名写得特别随意参数就是城市名和日期。结果模型经常把“上海”填成“上海市市辖区”日期有时候传成“明天”有时候传成“2025-06-15”返回结果五花八门。后来才意识到技能不是内部函数它是一份对外公开的接口契约读这份契约的是模型所以签约双方里必须把话说清楚。很多人刚起步的时候会不自觉地把技能当成一个“代码目录”觉得把工具类罗列出来、注册进去就行了。但实际跑起来会发现技能描述里多一句“当用户只提到城市而没有日期时默认使用今天”模型的成功率能提升一大截。这些描述不是写给人看的注释而是模型决策时最重要的情报。1.2 三个先想清楚的问题动手设计技能库之前我建议先花时间想清楚三件事。第一技能的服务对象是谁是终端用户直接通过对话触发还是由上游Agent内部调用。不同的调用方对描述的控制粒度完全不同。第二技能的失败边界在哪也就是技能内部抛出异常之后应该返回什么样的结构化错误是让模型重试、换一种参数还是直接道歉放弃。没有这层边界模型经常会陷入同一个错误里反复打转。第三技能的复用范围有多大是不是两个场景都在用同一份数据新建技能还是扩展已有技能。这三件事听起来简单但我在不同项目里反复吃亏尤其是第二件。一个新增的技能如果不定义错误码模型在拿不到结果时就会“编结果”这种问题比单纯报错更难排查。后来我养成了习惯每个技能返回的结果里必须带上状态字段成功是success失败是failed并且附上给模型看的简短原因。这样模型至少能基于真实信息做下一步决策。2. 技能库的整体设计与分层思路2.1 技能描述模型理解的第一道关卡如果把技能比喻成商品那描述就是贴在货架上的标签。标签写得模糊顾客要么找不到要么拿错商品。我见过太多技能描述写成了功能说明书比如“从数据库查询用户信息支持按姓名、手机号、邮箱查询返回匹配的用户列表如果有多条记录请让用户确认”。这句话看起来没毛病但模型在一长串技能列表里做匹配时不会像人一样逐字阅读它更倾向于根据“语义相似度”快速命中。更好的做法是把能力、触发条件、边界条件压缩成三四句话并且用模型容易建立关联的词语。比如“查询用户资料当用户询问自己的信息、资料、档案、账户状态时使用。参数中必须包含用户唯一标识缺少时主动询问。如果用户提到多个标识以手机号优先”。描述里真正起到区分作用的是那些“当用户说X时”之类的触发信号。我后来还在描述里添加了“不要用于”的约束比如“不要在对话开场时主动调用”这能把误唤醒率降下来不少。2.2 参数模式比类型注解多一点参数定义这块很多框架只让你写参数名和类型但实际经验告诉我描述参数语义才是决定成败的地方。模型填充参数时它理解的是参数名对应的“自然语言含义”而不是JSON Schema里的类型约束。举个例子一个参数叫release_date类型是string模型很可能会把“昨天”直接传进去而不是先做日期归一化。而如果你在描述里写清楚参数格式约束“格式为YYYY-MM-DD如果用户给出的是相对时间请先换算成具体日期再填入”模型的表现会立刻不一样。我在实际项目里采用了一种强化参数约束的做法把每个参数拆成“名称、类型、必填、取值范围、格式说明、示例”六项。其中示例特别关键相当于给模型提供参照物。测试下来有示例的参数填充成功率比没有示例的高出不少。还有一个容易被忽略的点——参数的排列顺序。模型在构造调用时会按你定义的顺序生成参数把最容易出错的参数排前面并配清晰的说明比一股脑塞在末尾要好得多。2.3 运行时上下文把状态交给技能技能不是每个都在真空里运行的。很多技能需要依赖当前用户身份、对话历史、上一步操作的结果等运行时信息。如果把这些信息全塞进参数让模型反复传递既浪费token又容易出错。更合理的办法是设计一套“技能上下文”机制在执行技能前把上下文对象注入进去技能内部按需读取。比如我有个技能是“查询订单状态”它需要当前用户的ID。如果让模型每次从用户话里提取那么当用户只说“我的订单到哪了”时模型会因为缺失用户ID而不知所措。实际上用户登录后用户ID已经保存在会话上下文里技能直接读取即可。这个设计还顺带解决了一个安全问题敏感信息不用暴露在模型可见的prompt里只在技能执行层使用。2.4 技能版本与依赖管理技能库发展到一定规模后版本管理迟早要提上日程。最初我的技能库就一个Python包所有技能堆在一起改一个参数就可能影响好几个下游调用方。后来遵循一个简单的原则每个技能模块有独立版本号技能之间的依赖关系显式声明。发布时打上技能版本标签并且在调用日志里记录版本号这样出现问题后可以快速对比新旧版本的输入输出差异。我踩过的典型问题是“隐式依赖”一个技能内部偷偷调用另一个技能的函数但没有在依赖声明中注明结果重构时改坏了。现在我把技能间的调用限制在“上下文”和“公共工具层”两个入口禁止跨技能函数直调。虽然重构成本增加一点但整个技能库的可维护性明显提高。3. 核心实现从注册到调用的完整链路3.1 技能注册表的实现技能注册表是整个技能库的心脏简单说就是一份“技能蓝图”的索引。我实现它时没有用复杂的框架核心就是两张表一张记录技能元数据包括名称、描述、参数JSON Schema、版本一张记录技能实现函数也就是Python可调用对象与元数据的映射。注册时统一走一个装饰器声明技能后自动把元数据和函数绑定并做基本校验。from dataclasses import dataclass, field from typing import Callable, Any dataclass class SkillSpec: name: str description: str parameters: dict version: str 1.0.0 handler: Callable[..., Any] None SKILL_REGISTRY: dict[str, SkillSpec] {} def skill(name, description, parameters, version1.0.0): def decorator(func): spec SkillSpec( namename, descriptiondescription, parametersparameters, versionversion, handlerfunc, ) SKILL_REGISTRY[name] spec return func return decorator注册时还需要校验参数Schema是不是一个合法的JSON Schema有些框架对格式宽松但我在入口处就拦截不合规的定义避免运行时才发现问题。注册表还可以扩展一个“加载状态”字段用来支持后面的灰度发布。3.2 调用循环让模型决定何时用技能真正和模型交互的调用循环我一般设计成三步。第一步把注册表里所有技能的描述和参数信息组装好塞进系统提示词中。第二步模型在生成回复时如果判断需要技能会输出一个结构化的调用意图比如一个函数调用对象。第三步框架拦截这个调用意图从注册表找到对应技能并执行然后把结果以“工具响应”的形式继续抛回给模型。这个过程里最容易出问题的是第一步的组装顺序。技能一多系统提示词会被撑得很长。我在反复实验后发现不能简单把技能列表一股脑排上去需要做“技能预筛选”。简单做法是维护一个“技能路由表”根据会话主题先模糊筛选出候选技能再放进模型输入。比如电商场景只加载订单、支付、售后相关技能不加载会议相关的。这能让模型做决策的信息噪声大幅减少。3.3 结果反馈错误信息也是上下文技能执行完成返回值不是终点。我调试过一个有趣的现象技能返回了“查询成功但数据为空”模型却回答“查询到了数据”。排查发现响应格式里缺少了状态的表达。后来我统一了返回响应结构内容包括三个字段status、data、message。status标记指令是否成功data是模块数据message是给模型看的简短说明。错误信息也要对模型友好。如果技能内部抛了底层异常原始堆栈没法直接给模型看需要翻译成“技能执行失败原因目标服务响应超时”并附带“建议稍后重试或让用户检查网络”。这一步是经验活错误信息写得太笼统模型会不知所措写得太具体又会泄露内部细节。我的原则是在控制台里留完整错误栈给开发者在返回给模型的消息中只保留对决策有用的信息。3.4 并发与超时控制技能不是你自己写出来就行上线后你会面对各种交互压力。我第一版技能完全没有超时设置某个技能调用下游接口长时间无响应时整个对话流程卡死体验很糟糕。后来达成共识所有技能执行必须有默认超时时间比如10秒超时后返回timeout状态让模型告诉用户“当前服务响应较慢请稍后再试”。并发方面有些技能可并行执行有些则必须串行因为后一个依赖前一个的输出。我开始采用了一个简单执行策略对技能调用序列做依赖分析没有依赖关系的调用并行发起有依赖关系的分步执行。并行能显著缩短复杂任务的执行时间但也会带来额外的资源开销我通常会配合线程池并限量控制。4. 实际落地的编排案例4.1 场景设定一个跨平台信息管理助手单讲架构太干了拿一个我实际参与过的项目举例会直观很多。这个项目是一个“跨平台信息管理助手”用户可以通过对话完成日历安排、邮件整理、待办清单、资料检索等工作。它的核心是多个平台的数据接口而每个平台能力都以技能形式封装。我们希望用户尽量用自然语言操作减少机械命令。在这个项目里技能库一共有九类基础技能涵盖日历、邮件、文档、任务、联系人等。难点在于单一技能只能完成单一动作而用户往往提出复合需求比如“把会议室预订成功这件事通知参会者并添加到我日程里”。这时候单纯从技能库选一个技能就不够了需要编排逻辑把两个技能串起来。4.2 技能拆解四类技能的职责划分方案上我把几十个技能按职责拆成了四类这样做是为了让后续编排更清晰。第一类是“查询型技能”负责只读数据的获取包括查日历、查邮件、查文档。这类技能返回的数据结构比较稳定适合被其他技能引用。第二类是“操作型技能”负责真正写数据比如创建日程、发送邮件、修改任务状态。操作型技能必须具备幂等性设计同一操作被重复执行也不应产生重复数据。第三类是“复合编排型技能”内部组合了多步基础技能调用对外表现为一个完整流程。比如“创建会议并通知所有参会人”是一个复合技能它内部依次调用日历创建、联系人查询、邮件发送三个基础技能。第四类是“校验型技能”负责接收模型输出检查其是否符合业务规则。比如用户说“帮我把邮箱里所有广告邮件标记为已读”操作范围很大校验型技能会先统计邮件数量超过阈值就要求用户确认。四类技能分开之后技能库的扩展路径变得很清晰新加一个功能时先定位它是属于哪一类。4.3 编排策略技能间的组合与回退实际运作下来技能编排不能只靠大模型的临场发挥必须在设计阶段就给出编排规则。我用了两层策略。第一层对于高确定性的流程写成复合技能由代码控制执行顺序比如会议创建流程。第二层对于低确定性的流程只给模型提供技能“路由建议”比如“查询日程后模型可以选择创建事件、修改事件或删除事件”最终由模型根据用户意图选择。我印象很深的一次问题是用户说“把明天上午的会议都取消”。模型执行了“查询明日日程”拿回一批会议列表但并没有逐条执行取消操作只回复说“好的已为您取消所有会议”。这个问题的根源在于模型默认认为查询结果等于操作结果。我加的兜底是所有批量操作技能在执行后有“结果确认返回”机制把实际影响的任务计数反馈给模型逼着模型向用户汇报真实执行情况。这和“回退”不完全一样更像是操作闭环。4.4 效果与瓶颈观察上线后观察了近两个月的日志整体效果符合预期用户指令成功完成率能稳在一个比较高的水平。但瓶颈也逐渐暴露出来主要集中在两个地方。一个是模型调用链变长后延迟明显上升。一次复合技能编排可能要经历“模型选择技能—执行查询—返回结果—模型再决策—执行操作—返回结果”几轮往返每一轮都在消耗延迟。后来针对高频流程做了精简提示词并且把部分查询技能的结果缓存到执行上下文里省掉模型二次决策的成本。另一个是技能数量的扩展和模型选择准确率之间互相制约。技能超过二十个时全量加载会出现选择准确率下降。我不再一味增加技能数量而是开始设计“技能分组”和“分组路由”让模型先选分组再选组内技能。虽然多了一层跳转但准确率明显改善这份取舍我觉得是值得的。5. 常见问题与排查经验5.1 模型总选错技能选错技能的现象包括用户问订单模型却调用商品搜索用户说保存文档模型却调用新建文档。一开始我以为是模型能力不行排查后发现大部分是因为技能描述里缺少“触发场景”和“负向约束”。最常见的修复方式有两个给技能加“功能边界说明”以及在判断歧义明显的技能时让模型先向用户确认再执行。还发现一个规律多个技能描述里如果有大量相同词汇模型容易混。比如“查订单”和“查物流”描述都含“订单”、“物流”字样模型就分不清。解决办法是刻意在描述里用不同的场景词和目标词形成差异化信号。模型输入层面的修改往往比调整温度这类参数管用。5.2 技能参数经常报格式错误参数格式错误是最常见的问题之一。我遇到的情况包括日期格式不统一、数字被传成带单位字符串、枚举值没有遵守约束。排查后归纳出一个规律模型会根据描述产生“格式预期”而描述里的格式说明必须和JSON Schema严格对齐。有一个实用技巧是“参数预处理钩子”。在技能执行前加一层函数负责把模型传进来的原始参数做归一化处理比如日期文本转成时间戳字符串去空格数字单位规范化。这层钩子不解决所有问题但能拦截大量轻微错误降低模型重试的概率。5.3 长上下文下的技能遗忘对话轮次一多模型对技能的感知会变弱经常出现“早期提到过要用某个技能后面就忘了”。这是因为系统提示词被后续对话内容冲刷。一个有效手段是“关键技能重申”在对话轮次达到一定阈值后重新向模型注入当前会话中已经调用过的技能摘要提示模型继续沿用。另一个做法是把技能状态信息放到模型可见的“对话摘要”里例如“已创建会议主题、时间”模型后续回复时即使没有新的技能调用也能通过摘要判断是否还需要触发后续操作。这个设计大幅减少了用户在长对话里重复表达需求的情况。5.4 私有化环境下的部署限制如果你的项目是私有化部署技能库的某些能力可能用不上比如调用第三方在线服务、访问云端大模型接口。环境限制下技能执行质量会有明显下降。我在一个私有化项目里发现模型对工具调用的解析能力不如在线服务输出格式时不时出问题。应对办法是加入“格式自纠错机制”技能调用结果在解析时如果发现不符合JSON结构不用急着报错而是对输出文本做一次清洗再解析无法解析时返回明确错误信息让模型重新构造。自动化测试方面我会给每个技能准备一组模拟用户指令回归测试时跑一遍调用链路确保改动没有破坏原有解析逻辑。6. 下一步扩展与个人心得6.1 让技能具备可观测性技能库上线不等于事情结束。我发现尽早建设可观测性非常划算。我给每个技能加了指标日志记录技能名、执行耗时、成功/失败状态、模型调用轮次、参数摘要。这些日志在看板里展示出来后能直接反映出哪些技能是高频命中、哪些技能容易失败、哪些技能描述实际并没有被模型触达。当时有一个低频技能长期没有被调用大家都以为是没人用。我查了日志才发现是因为它的描述和另一个更高频技能产生冲突模型永远优先选择了后者。如果没有日志这个误判会一直存在下去。另一个场景是技能执行耗时异常日志能快速定位是哪一类参数触发了慢路径。6.2 让技能具备学习能力目前技能库是静态的模型不调用就永远不变。我后续计划加入一个“用户反馈闭环”每次技能执行后如果用户明确表达了不满意系统会记录一段交互轨迹定期人工复盘后把修正点更新到技能描述或参数约束里。这个过程虽然不算严格意义上的自动学习但它确实让技能持续进化。还有一种尝试是“技能预热”。根据历史调用统计预测下一轮对话最可能出现的技能提前把对应技能的描述放到更靠前的位置或者预先加载其运行依赖。这个措施在数据量足够的场景下效果明显但要注意用户隐私保护不能直接使用原始会话内容做预测只能使用脱敏后的统计特征。6.3 最后一点个人体会做了这么多轮的技能设计和调优我最深的体会是agent-skills的本质不是代码问题而是沟通问题。你要沟通的对象有两个一个是用户一个是模型。模型通过你给的描述理解整个世界你写得越清楚它表现得越靠谱。初期容易把时间花在堆新技能上后来发现把已有技能的描述和边界打磨清楚收益往往来得更快。我也越来越认同一个原则宁可少一个花哨技能也不留一个模糊技能。模糊技能上线后带来的错误调用和用户差评远比它带来的功能增量要亏。把技能面收窄把每个技能的触发条件、参数约束、失败处理打磨到位这种“精而不多”的思路在真实业务里行得通。