从标题里看到 agent-skills 的第一反应这不是一个普通的小工具而是一类越来越常见的系统设计思路把大模型的能力从“对话”拆成一组可被复用、调度、管理的“技能”。如果你正在做智能体Agent相关的项目一定感受过这种尴尬模型很聪明但让它稳定地完成一个多步骤任务却很难提示词写了一堆换个场景又要重写明明有几个通用能力却在每个业务模块里复制了一遍又一遍。agent-skills 就是针对这个痛点出现的它把Agent要执行的动作抽象成独立技能每个技能有清晰的名称、参数、校验逻辑和动作实现再通过一个调度层把它们串起来。这篇文章适合两类人一类是刚接触Agent开发想知道该怎么设计技能边界、怎么写技能定义、怎么做调用的同学另一类是已经在跑Agent流程但总被“模型乱调工具、步骤断掉、技能不好维护”折磨的开发者。我会结合自己的实操经验把技能建模、注册、编排、版本管理和常见坑都拆开讲一遍。没有太多玄乎的理论都是可以直接拿去做参考的方案。1. 先搞清楚agent-skills 到底在解决什么问题1.1 从“会聊天”到“会干活”Agent缺的是一套技能机制大模型原生擅长的是文字生成。你问它“帮我查一下明天的天气”它能回答得有模有样但如果你让它“先读取用户上传的日程表找出明天所有会议再为每个会议生成一封提醒邮件最后按时间顺序发送”这就不是单纯靠提示词能稳定搞定的事情了。模型需要调用外部工具、需要记住中间状态、需要在不同步骤之间做判断。这个过程本质上就是人干活时使用不同技能的过程。但大多数Agent项目一开始并没有“技能”这个概念只有“工具”。工具是一个函数输入参数输出结果。Agent可以决定调用哪个工具但它不知道这个工具适合在什么场景下用也不知道一个复杂的任务需要哪几个工具按什么顺序配合。你可能会把工具描述写得很详细塞进提示词里结果提示词越来越长模型的理解却越来越飘。agent-skills 要做的是在工具之上加一层语义层。技能不只是函数它包含触发条件、输入参数、执行动作、结果校验、失败恢复这些完整信息。模型看到的不是一个个孤立的函数而是一份“能力菜单”每一项都写清楚了“我是谁、什么时候用我、需要什么信息、我能产出什么”。这样Agent才更像一个有经验的工作人员而不是一个只会按按钮的机器人。1.2 技能库不是函数库核心设计差异很多开发者的第一反应是把技能直接做成函数注册表类似“一个字典key是技能名value是执行函数”。这样做能跑通Demo但离真正可用还差很远。我总结过两者之间的几个关键差异函数库只描述“能做什么”技能还要描述“什么时候做”和“怎么做才算成功”。函数库由开发者自己调用技能由模型根据用户意图和当前上下文选择调用。函数库返回的是结构化数据技能返回的是一段可被模型继续理解和使用的状态信息。函数库的异常处理是代码层面的技能的异常处理必须同时考虑模型是否能理解并调整计划。打个比方函数库是工具箱里的扳手、螺丝刀技能则是一本“维修手册”中的操作条目。扳手只能拧螺丝而“拧紧漏水的水龙头”这个技能包含了判断是否需要关总阀、检查密封圈、用多大力度拧紧、装好后怎么验漏。Agent需要的是后者而不是一堆零散工具。所以 agent-skills 的定位不是“又一个工具注册库”而是Agent的行为能力层。它关心的是技能怎么被Agent理解、怎么被安全地调用、怎么组合成完整业务流程。这个定位决定了你在设计时需要额外考虑很多东西比如技能描述的语气、参数的枚举范围、失败时的错误信息格式。2. 技能如何拆解与建模2.1 技能的最小单元意图、参数、动作、校验我设计过的技能结构基本固定无论技能是简单到“查天气”还是复杂到“安排会议”都会拆成四个部分意图intent、参数parameters、动作action、校验validation。意图描述这个技能解决什么用户需求帮助模型在多种技能之间做选择。意图写得越贴近真实用户口语模型召回越准。比如“查天气”的意图可以写成“用户想了解某个地点当前或未来的天气情况”不要写成“调用天气API获取JSON数据”。前者是用户视角后者是实现视角模型更擅长理解前者。参数是技能对外暴露的输入契约。每个参数要有名字、类型、是否必填、描述、可能取值。参数描述一定站在模型的角度写告诉模型这个参数应该从用户语句中怎么抽取。比如地点参数“location”的描述写“用户提到的城市名或行政区名支持中文名和拼音”这样模型才知道从“明天北京会下雨吗”里抽“北京”。动作就是实际执行的部分可以是调用函数、访问数据库、发送请求也可以是再调用一次模型生成结果。动作层最容易被忽略的是超时和幂等。尤其是带副作用的技能发邮件、写文件、扣款必须设计成可重试或可补偿的。校验包含两部分参数校验和结果校验。参数校验在动作执行前做防止模型抽错参数导致程序异常。结果校验在动作执行后做判断动作是否真的完成了目标。例如发送邮件技能不能只看API返回200还要确认收件地址、正文、附件是否符合要求。最好把校验结果也返回给Agent让它知道下一步该怎么调整。2.2 技能描述与注册给模型一份“菜单”Agent要正确使用技能需要看到一份容易理解的技能菜单。菜单太长模型会注意力涣散太短信息不够。我见过比较好的做法是分成两级第一级是“技能索引”只有技能名和一句话说明用于快速筛选第二级是“技能详情”当模型选中某个技能后再取出详细参数和方法。这样避免了把几十个技能的全量参数一次性塞进上下文。注册过程也不是简单的“加进列表”。每个技能都应有独立的命名空间避免重名。技能名我习惯用“动词名词”比如“get_weather”、“create_meeting”、“send_email”不要用抽象的名字如“tool1”、“utility”。因为模型对语义命名更敏感动词开头能帮助它判断动作属性。另外注册时还应该声明技能的权限级别。有些技能只能读数据有些技能会修改数据有些技能涉及外部系统操作。Agent在自主执行时如果权限级别不明确很容易出现“模型自作主张发邮件”的情况。我通常会在技能定义里加一个“permission”字段并设置默认策略高风险的技能需要用户再次确认低风险的技能允许自动执行。一个比较完整的技术定义长这样skill: name: create_meeting description: 创建一条日历会议邀请需要会议主题、开始时间、时长、参与人。 intent: 用户要求安排会议或创建日程 permission: require_confirmation parameters: - name: title type: string required: true description: 会议标题尽量简短 - name: start_time type: string format: ISO8601 required: true description: 会议开始时间 - name: duration_minutes type: integer required: true default: 30 description: 会议时长 - name: attendees type: array required: false description: 参与人邮箱列表 validation: pre: start_time 必须晚于当前时间 post: 返回的条目能在日历接口查询到这个示例里的参数不是简单罗列每条都给出了模型抽取时需要的hint。校验规则也不是只写“非空”而是可执行的条件最好能被代码直接解析。2.3 一个实用的技能Schema示例如果不想自己发明格式可以参考下面这个JSON Schema风格的写法。它兼容大多数Agent框架也可以直接作为配置文件加载。{ skills: [ { name: search_docs, intent: 用户想搜索团队知识库中的文档, description: 搜索内部文档库按关键词或标签过滤返回标题和摘要, permission: auto, parameters: { type: object, properties: { query: { type: string, description: 用户搜索关键词尽量完整保留口语表达 }, tag: { type: string, enum: [guide, faq, api, spec], description: 文档标签用于缩小范围 } }, required: [query] }, action: { type: function_call, name: knowledge_base_search }, validation: { pre: [query非空], post: [返回结果数不超过20条每条包含title和snippet] } } ] }这个Schema的好处是纯声明式不限制具体编程语言。你可以在Python、Node.js或Java里各写一套对应的适配器。声明式的技能库还能支持可视化编辑非技术人员也能参与维护技能描述。3. 编排与调用怎么让Agent按流程把活干完3.1 显式调用 vs 语义路由技能定义好了接下来是Agent怎么调用。就我看到的方案大体分两类显式工作流和语义路由。显式工作流像写剧本。你把步骤写死先执行技能A拿到结果再执行技能B。这种方式稳定性高适合业务流程固定的场景比如“订单处理校验库存 - 创建订单 - 扣减库存 - 发送通知”。每一步都不会乱缺点是不灵活用户只要换个说法或中途改变需求流程就僵住了。语义路由则像给模型一个方向盘。把所有技能描述塞给模型由模型根据用户输入自己选技能、自己决定顺序。这种方式灵活适合开放场景比如个人助理。但问题是模型可能选错技能或者跳过必要步骤。agent-skills 这类项目最终要解决的就是在两者之间找到一个平衡。我常用的办法是“混合模式”大流程用显式工作流约束流程内部的小动作用语义路由。比如“处理退款”整个流程是固定的但“识别退款原因并记录”这一步可以交给模型从几个技能中选择合适的表达。3.2 组合技能与暂停恢复状态的保存与恢复复杂业务很少只调一个技能。技能之间需要传递中间状态。我在早期项目里吃过亏Agent执行了技能A、添加了状态执行技能B时把状态弄丢了因为调用是无状态的每个技能都只拿到用户原始输入。后来我把技能执行上下文设计成一个贯穿全程的“状态夹”每个技能执行完成后都能往里面写入结构化数据下一个技能可以读取。状态的保存最简单的方式是全局字典但真正生产环境里不能这么做因为Agent可能中途等待用户输入或者被外部服务挂起几分钟。会话技能尤其需要持久化。我建议把技能上下文序列化为独立的JSON存到Redis或数据库里并关联一个session_id。这样即使服务重启也能恢复未完成的流程。还有一个细节技能暂停和恢复。比如“收集报销信息”这个技能需要用户分步提供发票、金额、事由不可能一次性拿全。技能应该支持“等用户输入”的返回状态把当前已收集的信息存起来等下一轮用户消息进来再继续。设计返回结果时我会专门定义一种状态码例如“NEED_MORE_INPUT”并把缺失项描述清楚模型读到这个状态码后就知道要主动追问用户。3.3 三种编排模式的适用场景比较模式写法稳定性灵活性适合场景固定工作流代码硬编码步骤高低表单提交、订单流转混合编排大流程固定 小动作语义路由中中工单处理、内容审批全语义路由模型完全自主选技能低高开放问答、个人助理我踩过最大的坑是全语义路由在长链路任务上的失控。模型会在第三四步时突然跳去执行一个看似相关但无关的技能。解决办法是限制“单轮最大技能调用次数”比如默认不超过8次超出强制收敛。这不光是为了防失控也是为了让用户等待时间可控。4. 技能管理与版本化4.1 技能包的目录结构技能多了以后管理比写技能的负担更大。我建议一开始就按“技能包”组织目录每个技能包拥有独立版本。一个典型的目录结构如下skills/ meeting/ v1/ skill.yaml actions.py tests/ v2/ skill.yaml actions.py email/ v1/ skill.yaml search/ v1/ skill.yaml这个结构和Python包或NPM包很像。技能包之间尽量不直接互相依赖依赖关系通过上层的编排层解决。为什么这么做因为技能版本升级时你可以只发布v2同时保留v1A业务继续用旧版B业务用新版互不影响。技能描述文件skill.yaml是整个技能包的“说明书”版本号字段必须在yaml里显式声明。加载框架会根据声明版本加载对应目录。每次修改技能描述或动作实现都要升版本不能用“改文件名”这种野路子。4.2 依赖与冲突处理技能之间经常会有隐性冲突。举两个我遇到过的例子两个技能都使用“状态码200”表示成功但一个技能返回的200只是接口层面正常业务层面实际失败另一个技能返回的200才表示完全成功。这种情况下如果Agent只根据返回码判断执行结果就会被误导。我建议给技能结果增加一个统一包装结构包含status、code、message、data四个字段。其中code必须由技能自己定义不能直接透传第三方API的code。另一个冲突是技能名称相似比如“send_email”和“send_reminder”模型容易混淆。解决方法是把意图描述写得更具体同时设置“excludes”字段声明哪些技能与当前技能冲突这样语义路由时可以自动排除。版本依赖的处理也要提前设计。比如技能B依赖技能A的某个参数结构。如果A从v1升级到v2参数变了B如果不知道就可能收到旧字段。一个简单的做法是技能包声明“compatible_versions”字段框架在加载B时检查A的版本是否在兼容列表里。不匹配就拒绝启动宁可先跑不起来也不能在运行中才发现数据不一致。4.3 如何做好技能测试技能测试不能只测“函数能否跑通”更要测“Agent能否正确调用”。我把技能测试拆成三层第一层单元测试。直接调用技能的动作函数传各种边界参数验证返回结果。参数缺失、类型错误、超时异常都要覆盖。第二层语义召回测试。构造一批用户自然语言query让模型从技能库中选技能检查每个query是否被正确路由到目标技能。这一步能发现描述质量差、意图重叠的问题。做法很简单把技能列表和一条query一起发给模型记录输出并标注正确技能。第三层端到端场景测试。模拟一个完整的多技能任务比如“用户想参加会议但先要搜索文档了解背景然后创建会议最后给参会人发提醒”。验证Agent能按顺序正确调用所有技能并且中间状态的传递不出错。我自己还会额外做“反向测试”故意用模糊表达或者带误导性的query看模型会不会选错技能。比如“查天气”里塞一个“我要看看明天适合不适合外出”模型若直接调用一个“导航”技能就是错的。反向测试能暴露出技能意图描述和边界条件的漏洞。5. 落地时踩过的坑5.1 提示词膨胀技能描述越多模型反而越糊涂第一次把20个技能的全量描述塞进系统提示词后效果立刻变差。模型开始张冠李戴把“创建任务”技能的参数用在了“创建会议”上。原因是上下文窗口被无关描述占满注意力被稀释。后来我把技能描述精简到最多三句话并只把索引列表放进主提示词。当模型表达出想用某个技能时再由框架按照索引加载详情。这个做法我称为“按需展开”实测下来召回率和准确率都稳定很多。如果你暂时不想改框架至少要对技能描述做压缩去掉冗余示例。5.2 参数校验缺失模型传了一个看似正常但离谱的值模型能理解语义但不太擅长严格遵守格式。比如技能要求ISO8601格式时间模型可能直接输出“明天下午3点”。如果你直接把这句话传给API程序就崩了。我建议每个技能参数都加一层“归一化”处理而不是简单校验。归一化是指将模型的自然语言输出转换成程序可用的严格类型。写一个较小的时间解析器支持“明天下午3点”、“12月5日15:00”这类常见说法。同理枚举参数也要做模糊匹配比如“高优”“紧急”统一映射为“high”。这个坑不解决就会出现“单元测试全过了线上跑几步就报错”的诡异问题。记住模型给出的参数永远不要全信动作执行前必须有一道强校验。5.3 技能冲突与优先级多个技能都能满足用户请求时怎么办当用户说“帮我安排一下明天”这可能触发“创建日程”技能也可能触发“查看日程”技能。如果两个技能都匹配模型会随机选结果时好时坏。我给这类场景加了“意图优先级”规则有写操作属性的技能优先级高于读操作例如“创建日程”高于“查看日程”涉及当前上下文的技能优先于泛化技能。优先级不一定要写在技能Schema里我习惯放在路由层。路由层有一个优先级列表每次语义召回后先按得分排序再按优先级加权。这样做的好处是调度策略可以独立于技能库调整不用每次改技能描述。5.4 常见问题速查表问题现象可能原因解决方案Agent频繁调用错误技能技能描述过长或意图互相重叠压缩描述细化意图增加excludes技能执行到一半断掉上下文状态未持久化引入session_id和状态恢复机制多步任务最后一步遗漏步骤缺少显式闭环校验增加最终校验技能或固定工作流技能返回了非结构化的文本动作层缺少结果解析统一result包装结构强制code字段版本升级后旧流程失效技能包参数变更未声明兼容版本使用compatible_versions升级前跑回归测试这里的每一个问题都是我实际调试中遇到过的不是从文档里抄来的。技能系统的复杂度不会因为你使用了大模型就消失它只是从“写逻辑”变成了“定义边界”。agent-skills 这种思路真正让我受益的不是那个技能注册代码而是它逼我把每个技能的边界、成功条件、失败后的恢复路径都想清楚。那些一开始觉得“不就是一个函数吗”的技能细拆之后往往都能发现意想不到的隐含假设。如果让我给你一个最小落地建议从三个技能开始用一个统一的Schema文件配一个简单的路由函数先跑通一个三个步骤的流程。不要一开始就追求几十个技能的大而全体系。技能库是会生长的等你的Agent真的被用户用起来再根据真实调用日志持续调整技能的描述、参数和优先级这个循环才是 agent-skills 真正值钱的地方。