1. 先把“agent-skills”拆开看它到底在解决什么问题这两年只要做 Agent 相关项目的人基本都会遇到一个很尴尬的现状模型能力越来越强可每次落地一个新场景还得从头把工具、流程、边界条件一点点喂给模型。今天写一个 prompt 告诉它“调用天气接口时记得传城市编码”明天换个项目再来一遍。agent-skills 这个概念说白了就是把“让 Agent 干活的技能”从模型和业务代码里单独抽出来做成一套可注册、可复用、可组合的独立模块。模型只负责理解意图、拆解任务和做生成真正执行动作的技能放在一个统一的能力层里谁需要谁取用而不是每个项目都重复造轮子。我最早接触这类思路是在给一个客服机器人做功能扩展的时候。当时团队里同时维护了三套工具注册逻辑一套写死在 prompt 里一套挂在业务流程中还有一套散落在各种函数代码里。改一个业务参数得同时改好几个地方那种感觉像是把一套乐高积木拆散后丢进三个抽屉玩的时候还得来回翻。后来我把所有可执行能力整理成一份技能清单每项技能有明确的描述、输入输出、调用地址和权限边界Agent 根据用户问题自动选择技能整个系统一下子清爽了很多。这也是我为什么想认真聊聊 agent-skills 这个方向。这篇文章不是要给你讲某个现成框架的 API而是想从“设计方法论 真实落地经验”的角度把 agent-skills 这套东西拆开它解决什么问题、建技能库时有哪些细节容易踩坑、如何让多个技能组合起来干一件复杂事以及项目上线后最常遇到的故障怎么排查。如果你正在做 Agent 应用或者想把团队里的智能体能力沉淀成可复用的资产这篇文章应该能给你提供一套可以直接照搬的思考框架。1.1 技能与模型的边界为什么需要单独抽一层很多初学者会问我直接把工具函数给模型不就行了吗模型本身能调用函数为什么还要抽象一层“技能”问题在于模型对工具的理解是“一次性的”你给它一个 JSON Schema它知道怎么传参但不知道这个工具在什么业务场景下该优先使用、什么情况下必须拒绝调用更不知道多个工具之间的先后依赖关系。举个真实例子。我做过一个企业内部知识库问答 Agent最初直接把搜索接口、文档解析接口、权限校验接口全部塞给模型。结果模型经常乱来用户问“帮我看看 A 部门的报销制度”它先调了文档解析接口再去调搜索顺序完全反了导致解析了一堆空文档然后报错。后来我把这些接口封装成三个技能查询权限技能、搜索文档技能、解析文档技能并且在技能描述里写明“必须先调用权限校验确认可访问后再搜索”。模型再傻看到技能描述里的使用约束也能按正确路径走。单独抽一层的核心价值就是把“模型不知道的规则”写到技能里。技能的描述、前置条件、后置动作、适用场景、禁忌都是给模型看的“说明书”。模型不需要记住每个 API 的内部逻辑只需要从技能清单里选出合适的技能并调用它。这相当于给 Agent 配了一本完整的《岗位操作手册》而不是把一堆散落的工具清单扔给它。另外从工程角度讲技能层还能统一处理日志、监控、熔断、审计。如果没有这层抽象每个工具函数都得自己写日志出了问题你在日志系统里看到的是一堆互相割裂的调用记录有了技能层一个技能调用的开始、结束、输入、输出、耗时都能统一埋点。后续做评估、做成本分析、做安全审计都轻松很多。1.2 一套可复用技能栈能省掉多少重复劳动我见过不少团队项目做完了沉淀下来的只有代码仓库里一堆业务代码下次开新项目又从头写一遍工具调用逻辑。这其实是很大的浪费。如果从一开始就把技能设计成可复用的模块效果会完全不一样。打个比方技能层就像一个家庭的“工具箱”。过去你需要修水管的时候临时去五金店买一把扳手修完就扔现在你有一面工具墙每件工具都有自己的位置和标签需要时直接取用用完再归位。以后哪怕换了个房子换了个项目这面工具墙还能搬过去继续用。具体能省哪些首先是 prompt 编写成本。传统做法里每接入一个新工具都要在 prompt 里写一堆工具说明还要小心控制 token 长度。技能层的做法是让 prompt 保持精简只放技能清单的索引信息详细的描述可以放到技能元数据里按需加载。其次是工具注册逻辑。封装成技能后外部服务接口变成统一的标准函数签名底层是 HTTP、RPC 还是本地函数Agent 不关心。再次是测试用例。技能库建起来后每个技能都有独立的测试集新项目直接复用测试集不用重新构造场景。还有一个容易被忽略的好处团队协作。过去一个 Agent 项目里提示词工程师写 prompt后端工程师写接口前端工程师调接口大家各干各的你也不知道对方的模块到底能不能配合。技能层相当于一个统一协议后端只要按协议暴露技能提示词工程师只要消费技能清单两边可以不互相等待。这个协作效率的提升对稍微大一点的团队影响非常明显。2. 构建技能的核心细节从输入输出规范到工具约定光有“把工具封装成技能”的概念还不够真正落地时最考验人的是细节。技能不是简单包一层函数就完事它要解决模型的“选择问题”和“执行问题”。选择问题是指模型能不能在合适的场景下选中这个技能执行问题是指模型能不能正确调用技能。围绕这两点我总结了几个必须花心思去设计的核心环节。2.1 技能描述让 Agent 知道“什么时候该用”技能描述可能是整个技能库设计中最容易被低估的部分。很多人写技能描述时特别随意比如“获取天气”结果模型在用户问“明天适合去爬山吗”的时候反而不调用天气技能因为描述里没有“爬山、出行、户外活动”这些触发词。另一个极端是描述写得太长把所有可能的情况都罗列进去模型反而被冗长的信息干扰选错技能。我常用的一个技巧是把描述写成三段式功能概述、触发场景、不能做什么。功能概述一句话讲清楚技能的作用触发场景列举 3 到 5 个典型问题句式不能做什么用否定句明确边界比如“不要用于查询历史天气仅支持实时天气”。这个做法在实测中效果非常好模型的技能选择准确率明显提升。另外技能描述里一定要包含“使用前置条件”和“调用后果”。比如一个发邮件的技能描述里要写清楚“调用后将真实发送邮件无法撤回需用户明确确认后才能执行”。模型看到这样的描述在用户没有明确同意之前大概率会先做确认动作而不是擅自杀出去执行。这属于用描述做安全边界的一个典型手法。2.2 输入输出与副作用定义老司机和新手最容易在这里分歧技能输入输出的定义直接决定了模型能不能正确传参。这里有一个原则很重要输入参数的命名和枚举值要尽量接近自然语言习惯而不是贴近后端变量名。举个例子我做过一个查天气技能最早的参数名是city_code、weather_type模型经常传错因为用户不会说“city_code”用户只会说“北京”。后来我把参数改成city_name城市名支持中文名并在参数描述里加了“如果用户说北京则传入‘北京’不要自行转换编码”。模型准确率立刻上来了。这个改动成本几乎为零但效果却非常显著。另外还要特别关注“副作用”的定义。所谓副作用就是技能调用后对外部世界产生的影响比如发送消息、写入数据库、扣费、创建订单。这类技能必须和只读类技能在定义上做出明显区分我习惯在每个有副作用的技能描述里加一个字段requires_confirmation: true同时要求模型的系统 prompt 里约定遇到带此标记的技能必须先向用户确认再执行。输出也不只是函数 return 值那么简单。技能的返回结果最好带一层状态包装至少包含status、data、error_message。模型拿到返回结果后能根据状态字段判断是否调用成功而不是自己去解析一堆异常。否则模型在结果里看到 HTTP 500根本不知道该怎么向用户解释。2.3 技能注册与权限边界别让 Agent 随意“踢门”技能注册表是 Agent 的“通讯录”。注册表里除了技能 ID、名称、描述之外还应该包含权限级别、调用频率限制、超时时间等元数据。比如“查询数据库”和“删除订单”绝不能有相同的权限级别前者可以允许模型在无人工干预时调用后者必须设置为高风险状态。权限边界这一块我的建议是宁可先收紧再根据实际场景放开。因为模型在复杂对话里偶尔会“自作主张”。之前我们上线过一个运维 Agent它可以根据用户指令执行服务器命令早期我们把权限定得比较宽结果有一次用户说“帮我查下磁盘空间”Agent 不知道从哪里学来的习惯顺手执行了rm -rf /tmp/cache。虽然没造成严重后果但把团队吓出一身冷汗。后来我们把所有写操作和高危命令都设置成必须经过二次确认并对命令做静态白名单校验只允许在提前声明的几个目录下执行。后来验证下来虽然多了一步人工确认但安全性提升了一个量级。技能注册表还决定了 Agent 的能力面。很多项目里模型对技能的选择是基于“可见技能列表”如果某些技能不在注册表里模型根本不可能调用它。这就意味着你想让 Agent 做什么就把它对应的技能暴露出来不想让它做的就别注册。不要指望“模型有判断力”模型的能力边界是你定义的不是它自己决定的。3. 实操从零落地一个 agent-skills 技能库理论部分聊了不少下面直接进入实操环节。我会用一个尽量完整的例子带你走一遍技能库的最小落地流程定义技能、注册技能、把技能交给 Agent、让多个技能配合完成一次复杂任务最后再用测试集验证。我尽量还原实际操作中的步骤和代码你可以直接照着改。3.1 第一步从最小技能开始先跑通一个完整闭环最小技能不要贪多选一个简单的只读功能即可比如获取指定城市的实时天气。目的不是功能本身而是把“技能定义 → 技能调用 → 返回结果 → 模型组织回复”这条链路完整打通。我在实际项目中使用的技能定义大概是这样的用 JSON 格式记录元数据{ skill_id: weather_query, name: 实时天气查询, description: 查询指定城市的实时天气。适用于用户询问天气、出行建议、户外活动安排等场景。仅支持国内主要城市不支持查询历史天气。, input_schema: { type: object, properties: { city_name: { type: string, description: 城市中文名例如北京、上海、广州 }, date: { type: string, description: 查询日期格式为 YYYY-MM-DD。若用户未指定日期则默认当天传空字符串即可。 } }, required: [city_name] }, output_schema: { type: object, properties: { status: { type: string, enum: [success, error] }, data: { type: object, properties: { city: { type: string }, temperature: { type: number }, humidity: { type: number }, wind_level: { type: string } } }, error_message: { type: string } } }, auth: { level: read_only }, timeout_ms: 3000 }看到这个定义你已经能理解技能层的基本结构description是给模型看的input_schema和output_schema是给模型传参和解析结果用的auth是做权限控制的timeout_ms是给执行层用的。所有信息都结构化模型和程序都能消费。接下来是执行层的代码。技能执行函数不复杂只需要接收一个参数对象返回一个统一结构的结果即可。以天气查询为例伪代码如下def weather_query_executor(params): city params.get(city_name, ) date params.get(date, ) # 这里替换为真实的天气服务调用 # 我一开始是先用 mock 数据跑通的 if not city: return {status: error, error_message: 缺少城市名} return { status: success, data: { city: city, temperature: 26, humidity: 60, wind_level: 3级, }, }这里有一个容易踩的坑执行函数里不要再尝试做“智能判断”。比如不要写“如果城市名是北京就特殊处理”业务逻辑里的特殊处理应该放在数据层而不是技能执行层。技能执行层一旦复杂模型可能猜不透它的行为测试也不好做。3.2 技能注册与动态加载让 Agent 能“看到”它技能定义好之后需要注册到 Agent 的技能表里。注册方式取决于你的技术选型。早期我们用的是直接写死在系统 prompt 里的方案但技能一多prompt 长度立刻爆炸而且每次新增技能都要重新发一次消息成本非常高。后来我改成了“动态技能发现”机制用一个注册表服务维护所有技能Agent 启动或每轮对话开始时只拉取当前用户权限范围内的技能清单并优先输出技能名称和一句话描述给模型。模型需要查看某个技能的输入 schema 时再通过一个专门的查询接口按需获取。注册表的数据结构可以是这样的字段说明示例skill_id技能唯一标识weather_queryname技能名实时天气查询description给模型的说明查询指定城市的实时天气...input_schema输入参数定义JSON Schemaoutput_schema输出结果定义JSON Schemaauth_level权限级别read_only / write / high_riskrequires_confirmation是否需要用户确认falseversion技能版本1.2.0enabled是否启用true到这里Agent 已经可以根据用户对话内容从这两三个字段里判断该不该调用weather_query。我实测过在技能数量不超过 30 个时这种“先给名称和短描述再按需加载详情”的方式既省 token 又不会让模型迷失在大量工具定义里。注册完技能后还要在 Agent 的系统层加一个调度函数逻辑大概是接收模型输出解析出意图和参数查找命中技能执行返回结果。这部分不同框架差异很大但核心思想一致模型不是直接调函数而是请求调度器执行某个技能。3.3 编排多个技能把顺序、条件和兜底都写清楚单个技能跑通并不等于完成真实业务中会遇到多技能协同的场景。比如用户问“我下周去杭州出差帮我看看那时天气怎么样顺便推荐两个适合带小孩去的室内景点”。这个问题至少涉及三个技能查询行程日历拿具体日期、查询杭州天气、查询适合亲子游的室内景点。而且这三个技能是有顺序依赖的必须先确定出行日期才能查天气必须知道天气是下雨还是暴晒才能推荐“室内”还是“室外”。技能编排方案我见过几种最粗暴的是让模型自己在一次回复里连续调用多个工具。这种方式对话轮次多、失败率高。另一种是设计一个“编排技能”它的执行逻辑里串联多个子技能。比如定义一个travel_plan_skill它的 executor 内部依次调用日历查询、天气查询、景点查询最后汇总结果。这样模型只需要调度一个技能子技能之间的依赖关系由代码保证可靠性比让模型一步步自己调高很多。在编排技能时有两个细节很重要。第一是子技能的中间结果要能暂存避免重复查询第二是任一子技能失败时要有兜底方案。比如天气服务超时可以让它返回“天气未知”但景点推荐依然要继续而不是整体失败。这样用户至少能得到部分有用信息。我还习惯在编排技能的描述里写明“该技能会自动完成多步查询适合复杂旅行规划咨询如果用户只问单一景点不要调用此技能”。这个负负描述其实也是给模型做路由让简单问题走轻量技能复杂问题走编排技能避免杀鸡用牛刀也避免模型把简单问题错误地编排成一大串流程。3.4 技能测试与评估不能只试“一次成功”很多人建立技能库后只在开发环境里手动调几次看着模型成功调用了就认为大功告成。但真实场景中用户问题千变万化同样的技能可能在十种语境下触发失败。所以技能测试一定要做成自动化回归集。我目前用的测试框架不算复杂维护一批 prompt 测试用例每条用例标注预期应该调用的技能、预期参数、预期返回状态。代码跑起来后自动调用 Agent比较实际调用的技能/参数是否和预期一致。这个回归集既可以在开发阶段用也可以在每次修改技能描述后跑一遍防止“按下葫芦浮起瓢”。举例来说天气技能至少要有这些用例用户说“北京今天冷吗”预期命中weather_query参数city_name北京用户说“上海明天下午会下雨吗”预期命中weather_query参数city_name上海用户说“查一下历史天气”预期不应命中weather_query模型应回复不支持并引导用户使用其他服务用户说“帮我查一下纽约天气”预期模型应询问是否指代其他城市而不是直接传city_name纽约因为技能只支持国内城市这类测试看起来简单但非常能发现问题。我跑第一轮测试时发现模型在“历史天气”这种否定场景中经常会误调用后来在描述里加了“不支持查询历史天气”错误率立刻下降。可见评估数据不是摆设它是让技能描述持续变好的润滑剂。4. 常见问题与排查技巧实录技能库上线后真正磨人的其实是各种边界问题。我把自己实际踩过的坑和排查思路整理成一份速查笔记希望能帮你省掉一些不必要的加班。4.1 我踩过的坑和排障过程第一个坑是“技能描述与真实行为不一致”。我们曾经把一个搜索技能描述得很强大说“支持全文检索、语义检索、关键词匹配”但底层接口只接了关键词匹配。结果模型在用户问语义相近的问题时调用该技能返回结果为空然后傻乎乎地告诉用户“没有找到相关内容”。这类问题最大的隐患是模型不会主动识别技能本身的缺陷它会用一套听起来很自然的话术掩盖底层服务的不足。后来我们定了一条规矩技能描述只能基于真实能力来写宁可写保守一点也不要夸大。第二个坑是“参数里藏着隐式转换”。早期查订单技能输入参数是order_time我们要求模型把用户说的时间转成时间戳。但不同时区的模型转换结果不一致经常出现时间差 8 小时的问题。排查了很久才发现是模型在做隐式转换时采用了 UTC而业务系统用的是北京时间。解决办法很简单把输入参数定义改为 ISO 8601 字符串并明确要求“不要转换时间戳直接传原始时间字符串”由技能执行层统一处理。这又一次验证了那句话复杂度要从模型那里移除放到代码里。第三个坑是“多技能并发导致的竞态条件”。有一次做批量处理任务Agent 同时调用三个写技能结果两个技能同时更新了同一条记录最后的数据状态是乱的。这个问题的根源是技能层没有做锁和幂等控制。后来我规定所有写技能都必须实现request_id参数执行层根据request_id做幂等判断同一请求重复执行只会生效一次。同时给高风险写操作加分布式锁彻底解决了这个问题。4.2 问题速查表下面这张表建议直接截图存起来排查问题的时候对照着看现象可能原因排查思路模型该调用技能却没调用技能描述太窄没有覆盖用户场景检查描述里的触发场景补充更多同义表达模型调用了错误的技能多个技能描述相似边界不清晰在描述中增加否定边界明确“不要做某事”参数传错或格式不对参数命名不够自然、缺少示例参数命名贴近自然语言在描述里给一个例子技能调用成功但结果不符合预期技能内部逻辑 bug 或下游服务异常先看技能执行层日志确认返回的status和error_message对话变慢技能清单太长或系统 prompt 过大改为动态加载只暴露当前会话可能有用的技能技能重复执行没有幂等控制引入request_id同一请求只处理一次用户无权限却调用成功技能注册表未做用户级权限过滤注册表按用户角色过滤技能而不是只过滤系统级权限模型自行编造技能结果技能超时或返回异常后模型过度生成给技能调用加超时熔断返回错误消息强制模型如实回复4.3 几个被低估的细节最后分享三个容易被忽略但影响很大的细节。第一个是技能版本管理。技能不是一成不变的业务调整了技能实现和描述都要升级。如果不做版本管理排查问题时很可能看到模型还在用旧版本描述而执行层已经换了新实现两边不一致各种奇怪问题都会出现。我的习惯是每个技能定义里都带version字段并在日志中记录每次调用时模型看到的技能版本号这样才能把“模型认知”和“实际执行”对齐。第二个是技能灰度发布。技能描述的小改动可能影响模型的选择行为甚至引发连锁反应。所以重要技能修改后不要立刻全量上线可以先让 5% 的流量走新版本跑几天看指标没问题再全量。这个方法让我们避免了好几次上线事故。第三个是技能的可解释性。用户有时候会质疑 Agent 的行为比如“为什么没调用我买的 VIP 权益接口”。为了让用户信服我每次技能调用都会生成一条调用记录前端对话页面上可以展开查看当前轮次调用过哪些技能、传了什么参数、返回了什么结果。这个记录既是排查工具也是用户权益的证明。透明永远比黑盒让人放心。说实话做了这么久的 Agent 相关项目我觉得能把 agent-skills 这层做明白的人做出来的智能体应用在稳定性、可维护性、安全性上都会明显高一个档次。技能层不是中间多出来的一道繁琐流程而是把混乱变清晰的必经之路。你在实际落地时如果也遇到了什么怪问题欢迎按上面的排查表先自查一遍多数情况下问题都藏在描述、参数、权限、幂等这几个环节里。