Agent技能库设计指南：从零搭建可复用的agent-skills体系

做Agent开发这几年我最大的一个感受是模型决定了Agent的下限技能agent-skills决定了Agent的上限。同样的基座模型有人做出来的Agent只会陪聊有人做出来的Agent却能在后台自动跑数据报表、处理工单、写代码改bug差别基本都出在技能这一层。这篇文章我想把从零搭一套Agent技能库的完整思路、代码落地和踩坑过程梳理出来不涉及某个特定框架的源码细节而是聊一套可以迁移的方法论给你正在做的Agent项目做个参考。先说明白一点我这里说的技能指的是给大模型封装好的一组可调用能力类似工具Tool、插件Plugin但又不完全一样。它是一个更偏任务级的概念——一次技能调用应当完成一个相对完整的业务动作而不是暴露一个原子操作给模型。这个认知差异是我后期重构技能库时最重要的转折点。1. 技能设计的底层逻辑先搞清楚Agent是怎么用技能的1.1 技能、工具、插件到底有什么区别很多刚接触Agent的人会把技能、工具、插件混为一谈但它们的使用场景和设计目的差别很大。工具Tool是最底层的原子能力比如查天气发HTTP请求执行一段Python代码。它只关注能做什么不关心为什么要做。插件Plugin通常是第三方系统提供的功能扩展包比如一个Shopify插件、一个Slack集成它是有边界的、由外部平台定义的。技能Skill是介于两者之间的一层它把多个工具调用、多步推理、某种领域规则组合成一个完整任务单元。举个例子一个生成月度销售报告的技能内部可能要调用查询数据库、生成图表、格式化文档三个工具并且按固定顺序执行。对Agent来说它不需要知道这三个工具的具体实现只要告诉模型调用这个技能就能得到一份月度销售报告即可。这个区别看似简单但直接决定了你的Agent是模型在指挥一堆散装工具还是模型在调度一个能力体系。前者到了任务复杂一点就乱套后者才能支撑真正的业务流程。1.2 为什么技能设计决定了Agent的上限模型负责的是理解和决策技能负责的是执行和落地。一个再聪明的模型如果手里只有几个粗放的工具遇到真实业务场景也会处处碰壁。我举个实际例子。早期我做一个客服工单分类Agent给模型暴露了一个调用数据库查询工单信息的工具参数随便传。结果模型经常传错表名、把字符串当整数、甚至尝试用SELECT * FROM ticket WHERE 11去获取全表。后来我把这个工具收拢成一个技能fetch_ticket_detail内部封装了表名映射、字段校验、超时重试、返回裁剪模型只需要传一个工单号问题瞬间消失。这就是技能设计的核心价值把不确定性挡在技能边界之外让模型只面对高层的、稳定的接口。模型不容易犯错你的系统也更健壮。1.3 技能库的分层架构我现在的技能库一般分三层基础技能层通用能力比如执行代码读写文件搜索网络。这些几乎任何Agent都需要跟具体业务无关。业务技能层跟业务强相关比如查询销售数据生成业务报表发送营销邮件。这层是技能库的主体需要持续迭代。编排技能层跨多个业务技能的组合任务比如每日经营晨报会先后调用数据查询、图表生成、报告汇总三个技能。这层更像是一个流程模板。分层的目的很明确越底层越稳定越顶层越容易变化。模型在顶层做编排在中层选业务能力在底层执行动作。我在实际项目里按这个思路整理后技能的新增和维护效率提升了很多也减少了改一个底层工具导致所有Agent出问题的连锁事故。2. 技能定义的核心细节描述、参数与返回值的玄机2.1 技能描述写给模型的说明书不能偷懒一个技能能不能被正确调用很多时候不取决于代码多健壮而取决于描述文本写得好不好。模型是通过描述来决定要不要调用这个技能什么时候调用的描述写得含糊模型就瞎猜。我写技能描述的经验可以归纳成三个原则第一说清楚什么时候用。比如一个查询销售数据的技能描述里不要只写查询销售数据而要写当用户询问销售额、订单量、区域业绩等销售指标并且需要从内部数据库获取时使用本技能。第二说清楚输入是什么。把关键参数的含义、格式、取值范围写进去比如时间范围使用YYYY-MM-DD格式不传默认最近30天。第三说清楚输出会是什么。让模型在调用前就知道结果长什么样这有助于它判断是否需要进一步处理或调用其他技能。我见过太多人把技能描述写成一行字然后就抱怨模型乱调用技能。实际上模型没有常识去猜你的接口它唯一的依据就是你写给它的那段文字。把描述当成给一个实习生看的操作手册来写怎么细都不为过。2.2 参数Schema把决策空间留给模型把约束留给自己参数Schema设计是个平衡题。给模型的自由度太大它容易传错自由度太小每个调用都要经过复杂校验又失去了Agent自动化的意义。我的经验是业务上必须有默认值的参数统统在技能内部兜底不要暴露给模型只有那些真正需要模型从用户输入中提取关键信息的字段才放到Schema里。比如一个发送报告邮件的技能收件人列表、正文模板、抄送规则这些都应该在技能内部定义好模型只需要传报告类型和统计时间范围两个参数。这样既减少了模型出错的可能也让接口对模型更友好。另外参数类型一定要写清楚并且严格校验。实际操作中模型经常把数字参数传成字符串或者把最近三个月翻译成3而不是90天。为了应对这种情况我在技能入口处统一做了一层参数规范化和校验遇到格式不对的先尝试转换转换失败再回退到默认值并记录日志。这个兜底机制非常有用。2.3 返回值模型能看懂比格式化漂亮更重要技能的返回值要分两套来看一套给业务系统用比如写数据库、调接口另一套给模型看决定它下一步怎么走。给模型看的返回我建议在最前面加一段summary字段用自然语言描述本次执行结果比如已成功查询2024年1月至3月销售额总计约250万元同比增长12%明细见data字段。模型的注意力有限如果一上来就是一坨JSON它往往抓不住重点就会做一些奇怪的后续动作。而详细的业务数据放到data字段里供需要精确计算或展示时读取。这两个字段分开是我调了很久才养成的习惯。以前我把所有东西混在一个大JSON里返回模型经常忽略关键数字或者自己脑补一个结论后来拆成summarydata这类问题基本绝迹。2.4 技能类型确定性技能与学习型技能的组合技能还可以按是否随数据变化分成两类确定性技能逻辑固定结果可预测比如查询数据库生成图表发送通知。这类技能实现简单测试成本低占技能库的大部分。学习型技能行为需要根据历史数据持续调整比如智能推荐异常检测话术生成。这类技能通常要内嵌一个模型或规则引擎或者调用一个外部推理服务调试和维护成本高。我建议技能库里80%以上都是确定性技能学习型技能只在确实需要的地方引入。曾经有团队把一个智能生成广告文案的技能做成全动态的结果每次返稿质量波动很大后来加了人工审核和固定模板兜底才稳定下来。技能是给Agent用的生产工具稳定性和可预期性是第一位的花哨但不稳定的技能只会拖垮整个Agent。3. 从零构建技能库一个可复用的实操全过程3.1 场景设定做一个经营数据分析助手为了把上面的方法讲透我拿一个真实的案例来演示给一个零售公司搭建经营数据分析Agent需要让Agent能够根据自然语言查询销售数据并输出分析结论。我先列技能清单查询销售明细query_sales_data生成可视化图表generate_chart生成分析报告文本generate_insight_text发送日报邮件send_daily_report_email检测销售异常detect_sales_anomaly这五个技能覆盖了从取数、分析、展示到分发的完整链路。每个技能都是独立模块可以在不同Agent中复用。3.2 技能的内部实现以查询销售数据为例我不会用某个特定框架的写法而是给你一种语言无关的设计思路。核心思想是技能接口暴露给模型的永远是一个稳定签名内部封装所有易变逻辑、校验、容错和日志。# 技能query_sales_data class QuerySalesDataSkill: name query_sales_data description ( 当用户需要了解销售额、订单数、客单价等销售经营指标时使用。 可查询指定时间范围、指定门店/区域的数据。 时间范围格式为YYYY-MM-DD不传则默认最近30天。 返回结果包含summary摘要和data明细。 ) parameters_schema { type: object, properties: { start_date: {type: string, description: 开始日期格式YYYY-MM-DD}, end_date: {type: string, description: 结束日期格式YYYY-MM-DD}, region: {type: string, description: 区域或门店编码可选不选则查全部} }, required: [] } def execute(self, start_dateNone, end_dateNone, regionNone): # 1. 参数归一化补默认值、格式化 start_dt, end_dt self._normalize_dates(start_date, end_date) # 2. 业务查询连接数据仓库等 df self._query_from_warehouse(start_dt, end_dt, region) # 3. 构造summary关键结论摘要 summary self._build_summary(df, start_dt, end_dt) # 4. 裁剪data控制返回体积防止超token限制 data df.head(100).to_dict(orientrecords) return {summary: summary, data: data, row_count: len(df)}我特别强调两个细节。第一个是参数归一化。模型传来的start_date可能是2024-01-01、、None甚至最近三个月这种自然语言技能内部要把这些情况全部处理掉。我在_normalize_dates里做了一个友好的解析遇到纯自然语言就先让模型重试但更可靠的做法是要求前端在调用前做一轮清洗。第二个是返回数据的裁剪。数据库里可能查出几万行但Agent上下文窗口有限我设置了最多返回100行明细同时把总数放在row_count字段里。summary字段里会说明本次查询共返回12345条记录以下展示前100条。这样模型既知道全貌也不会把上下文挤爆。3.3 技能注册与调度让模型知道技能的存在技能实现之后还要注册到Agent的运行时里。不管用的是开源框架还是自研的调度器本质都是做三件事把技能的name、description、parameters_schema拼进系统提示词等到模型请求调用时路由到对应的execute函数然后把返回值回传给模型。# 伪代码技能注册与调度 class SkillRegistry: def __init__(self): self.skills {} def register(self, skill): self.skills[skill.name] skill def get_system_prompt_skills_block(self): # 生成给模型看的技能说明书 blocks [] for name, skill in self.skills.items(): blocks.append( f### 技能: {name}\n f说明: {skill.description}\n f参数: {json.dumps(skill.parameters_schema, ensure_asciiFalse)}\n f调用格式: {name}(参数JSON)\n ) return \n.join(blocks) def dispatch(self, skill_name, parameters): skill self.skills.get(skill_name) if not skill: return {error: f技能 {skill_name} 不存在} try: return skill.execute(**parameters) except Exception as e: return {error: f技能执行异常: {str(e)}}注册技能时最容易被忽视的就是技能在系统提示词里的排序。模型面对一大串技能说明时注意力会集中在靠前的位置。所以我把高频技能放在前面低频技能放后面并且用### 技能: xxx这样的结构化标题分隔。实测下来调用准确率有明显提升。还有一点不要一次给模型挂太多技能。技能数量在10个以内模型的选择准确率通常还可以超过20个误选率就开始明显上升。如果你确实有几十个技能就要靠分组或者先经过一个路由技能来做粗筛而不是一股脑全塞进去。3.4 技能评估怎么知道一套技能库是好是坏技能库不是写完就完事的它需要持续评估和优化。我建立了一套简单的评估方法分享给你参考。评估集准备50到100条典型的用户请求覆盖高频场景和边界场景比如帮我查一下上海门店上个月的销售额跟去年同期比怎么样哪个品类卖得最差。评估指标技能选择正确率模型是否选对了要调用的技能。参数抽取准确率模型是否从用户请求中正确提取了参数。执行成功率技能内部是否正常运行有没有抛异常、超时、返回空数据。结果有用率返回的summary和data是否能支持用户下一步决策。这四个指标是递进关系。从实际操作看第一个指标最影响体验一旦模型选错技能后面全是白搭而选错技能的原因八成又是描述写得不够清楚。所以我在评估集跑完之后第一件事永远是回头改描述而不是改代码。3.5 技能的版本管理与迭代技能会随着业务演进而变化。我见过最痛的情况是销售团队改了数据口径技能代码里还是旧逻辑Agent给出的报表跟人工报表对不上业务方直接失去信任。所以技能库必须做版本管理。我的做法是每个技能都有一个version字段和一个changelog字段调用时会把技能版本记录在日志里技能改动必须走旧版本并存—灰度验证—新版本切换的流程。尤其是涉及数据指标口径、金额计算、时间范围默认值这类变更宁可多花时间验证也不能直接线上改。版本管理还有一个好处当某个Agent行为突然异常时可以第一时间判断是不是某个技能的版本变更引起的。这比对着代码库一层层翻git历史高效得多。4. 常见问题与排查技巧实录4.1 模型就是不调用某个技能怎么办如果你发现模型在应该调用技能的时候没有调用或者一直在尝试自己回答而不是走技能通常不是模型笨而是技能的存在感太弱。排查顺序先看系统提示词里技能说明书是否完整、是否清晰再看技能描述里有没有明确的当用户……时使用本技能句式最后看返回内容的summary是否有价值如果模型觉得我自己推理也能得出答案它就不会想调用技能。经验之谈想办法让技能产出模型单凭自身知识拼不出来的信息比如内部数据库的精确数字、第三方系统的实时状态。一旦模型意识到不调用就拿不到这个数据它自然会形成调用的习惯。4.2 参数幻觉模型乱传参数怎么治模型传错参数几乎无法彻底避免但可以通过三层防线大幅降低第一层是描述约束注意在参数的description里写清楚格式和示例值。第二层是代码兜底在execute内部做值和类型转换尽量抗住错误输入。第三层是对话式澄清当模型传的参数明显异常比如日期早于业务开始时间、金额为负数让Agent先向用户确认再执行而不是直接报错。很多项目为了省事砍掉这一层结果用户看到的不是帮我确认一下而是一堆难看的错误日志体验很差。4.3 多个技能互相干扰技能多了以后模型可能会把多个技能的参数搞混或者在一个技能的逻辑里试图调用另一个技能的返回字段。我的解决办法是严格隔离技能A的返回数据绝对不能出现在技能B的输入Schema里两个技能之间如果要传递数据必须通过Agent的上下文来中转而不是让技能内部直接互调。还有一个常见坑两个技能的名字太像比如query_sales_data和query_sales_report模型很容易选错。我踩过之后把命名规范定为动词_对象_目的尽量让名字之间的语义距离拉开同时在描述里主动说明如果你想生成报表请用xxx技能不要用yyy技能。4.4 安全边界别让Agent拿着技能乱跑技能一旦被Agent调度就等于把一些操作权限交给了模型这里的安全边界必须提前设计好。我通常会给技能配置权限等级只读技能查询类、写入技能发送邮件、建工单、改配置、高危技能删数据、转账、执行外部命令。写入和高危技能默认不开放无限执行权必须配合审批流程或者限定操作范围比如只能操作本部门数据。同时把所有技能调用完整记录下来方便事后审计。另一个实际建议给技能加上频控和熔断比如单个用户每天最多触发多少次发送邮件技能如果某个技能连续失败超过阈值自动熔断并通知管理员。AI越智能越需要规矩管着别等到出事了再补安全措施。4.5 常见问题速查表现象大概率原因解决方案模型不调用技能描述不清晰或技能存在感弱重写描述加入触发场景让技能提供模型无法自行获得的数据参数乱传参数Schema约束不够加description示例代码兜底转换添加对话式澄清环节技能选错技能之间边界模糊拉开语义距离在描述中主动说明差异控制技能数量返回结果臃肿未裁剪输出数据增加summary前置摘要限制data条数移除冗余字段技能执行超时内部等待过久设置超时上限异步化长任务拆分为多个短技能线上行为突变技能版本变更未验证做版本管理灰度切换核对changelog上下文被占满技能返回过大或历史过多压缩返回清理旧消息使用摘要替代完整历史结尾最后说一点个人体会。技能库不是一次建完就一劳永逸的东西它需要跟业务一起生长。我见过太多团队花两周搭好一个看起来很完整的技能库后面再也没有人维护三个月后Agent的表现退化到没法用的状态。真正好用的agent-skills靠的是持续迭代每次模型升级、每次业务规则调整、每次用户反馈这个答案不对都应该回到技能描述和实现里去找原因。如果你正准备入手做Agent技能我的建议很朴素先拿一个真实业务场景手工写下这个场景需要的三到五个技能跑通一条任务链路再慢慢扩充。别一上来就追求技能数量多、覆盖广先把一条链路打磨到稳定再复制这套方法论到更多场景。技能这层做好了Agent才真正从能对话变成能干活。