agent-skills这个名字我在第一次看到的时候也愣了一下。它不像某个具体框架或者某个平台的SDK那么直观但它近几年在AI代理应用里被反复提及几乎成了搭建可靠Agent的默认底座。我自己经历了一个从把所有能力塞进一段提示词到把能力拆成一个个可注册、可调度、可评估的技能模块的转变回头再看这个转变本身才是让代理从Demo走向生产的关键。这篇文章想把我整理技能库、设计技能边界、构建技能评估体系过程中的经验完整写出来完整到你可以直接照着搭一套属于自己的代理技能体系。这篇文章适合已经在接触大模型应用开发或者正在用Agent框架写自动化任务的开发者。如果你现阶段只是写写脚本还没有被代理乱调用工具提示词越写越长但效果越来越差这类问题折磨过那正好可以先看看正确的组织方式长什么样。1. 为什么代理应用不再靠大提示词而靠技能库1.1 从单体提示词到技能模块的演变早期做LLM代理功能的时候很多人的第一反应是把所有指令全部写进系统提示词里比如你是一个助手你可以做以下几件事当用户查询天气时调用天气接口当用户需要计算时调用计算器……再配上一大堆详细步骤。一开始效果还行但随着功能增多提示词会膨胀到几千甚至上万字问题就接踵而至。首先是命中率不稳定。模型在超长上下文里经常漏掉某些指令尤其是藏在提示词中后段的工具调用说明经常被忽略。其次是维护成本失控。每次加一个新能力都要重新调整提示词结构改一处就可能导致其他能力表现退化。我在一个模拟客服项目里就吃过这个亏只是给提示词加了一个兜底转人工的逻辑结果AI连最基本的订单查询都不触发了。把能力拆成技能库之后提示词反而变短了。代理只需要知道当前场景有哪些技能可用、每个技能是干什么的具体怎么执行、执行边界在哪里全部由技能模块自己负责。这其实就是把传统软件工程里的模块化思想搬到了LLM代理里让提示词工具这种松散耦合变成更可控的意图技能结构。1.2 agent-skills 到底是工具还是动作很多人在拆技能的时候会纠结一个概念问题技能和工具Tool、函数调用Function Calling到底有什么不同我个人的定义是工具是逻辑层面的具体能力比如查数据库发HTTP请求而技能是在工具之上封装的、面向目标和场景的可复用动作单元。举个例子发送邮件可以是一个工具但给客户发送项目进度周报邮件就是一个技能。它内部可能包含查项目状态、生成周报模板、替换占位符、调用邮件服务、记录发送日志这五个步骤外面只暴露一个明确的输入输出接口。这种区别很关键因为代理在规划复杂任务的时候更擅长调用一个高层次的技能而不是自己组合一堆原子工具。如果让代理每次都要自己规划先查这个表、再调那个函数、然后再拼装结果出错的概率会指数级上升。所以agent-skills的本质是给代理提供既知其然又知其所以然的行动单元它告诉代理这个技能解决什么问题、什么时候应该用、输入输出长什么样同时也封装了内部的复杂逻辑。1.3 这个体系适合谁不适合谁如果是纯问答类应用不需要复杂的工具调用那技能库反而会显得笨重直接写提示词更简单。但如果你的应用要连续完成多步骤任务、要接多个外部系统、要允许不同团队往同一个代理里加能力那技能库就是刚需。还有一种不适合的情况你的代理任务高度固定比如每天就执行一条固定流程不需要动态规划。这时候把流程写死在代码里比让代理去理解技能表再调用要可靠得多。技能库最大的价值在于面对非固定路径、非确定输入的场景时保持既有灵活性又有稳定性。2. 搭建技能库前的两个关键设计决策2.1 技能粒度函数的边界就是技能的边界我见过不少第一次搭技能库的人最容易犯的错误是技能粒度失衡。太粗的技能像一个万能接口代理调用了它还得在内部做大量分支判断本质上又回到了单体逻辑太细的技能又退化成原子工具代理每次要调用七八个才能完成一个小任务推理负担极重。我总结了一个相对合理的粒度判断标准一个技能应当能独立完成一个对用户或系统有明确价值的最小闭环。比如查询订单并返回格式化摘要是一个闭环计算两个日期之间的工作日天数也是一个闭环但解析用户输入的时间表达式就不是闭环它只是某个闭环里的一步。在实际项目里我会先列出代理最常遇到的20个任务场景再为每个场景设计技能然后检查有没有重复覆盖。重复覆盖不是说两个技能功能相同不能用而是必须约定优先级和适用条件否则代理会陷入选择困难。2.2 技能描述的质量直接决定代理的调用准确率这里我想强调一个容易被忽视的细节技能描述的作用对象是LLM不是人。你写技能描述的时候不应该只想着把这个函数说明白而要想着让代理在什么状态下能一眼看出该用它。好的技能描述应该包含三个层次触发条件什么情况下适合调用它、执行效果调用后能完成什么、约束条件什么情况下不应该调用它。约束条件特别重要比如一个生成SQL查询的技能如果不写仅用于内部数据平台的只读查询禁止执行写操作代理可能会在需要更新的场景里误调用它造成风险。我在某次测试里做过对比同一个技能描述从一句话扩展成包含触发条件和边界约束的三句话后代理在50个测试会话里对该技能的误调用次数从9次降到了1次。这个实验很直接地说明多花几分钟打磨技能描述远比在提示词里反复强调你要仔细选择工具有用得多。2.3 技能命名、注册和版本管理技能命名也有讲究。我常用动词宾语的模式比如 get_customer_balance、send_approval_notification。这种命名对模型来说更加直观也方便在日志里快速定位问题。技能注册的时候要给每个技能分配一个稳定的ID不建议直接用函数名做ID因为函数名可能随着重构改变但技能ID最好保持长期稳定这样历史日志和评估数据才能对得上。版本管理方面我比较推荐参照接口版本化的思路技能的行为一旦有显著变化就开启新版本旧版本至少保留一个过渡期。因为代理的对话可能跨多个请求如果中途技能行为变了之前的状态就可能对不上。我在一个多轮会话场景里就碰到过第一轮调用的还是旧版技能返回的结果第二轮升级后代码已经切到新版本两轮的数据格式不一致直接把代理中间状态解析搞崩了。从那之后凡是可能影响输出的改动我都会走一次版本备案。3. 一个可复现的 agent-skills 最小实现3.1 技能定义的数据结构我目前最顺手的做法是用JSON来定义技能元数据再配合一个Python类来做执行入口。每个技能由三部分组成元信息、验证逻辑、执行逻辑。下面是我常用的一套结构脱去业务细节后的简化版{ skill_id: customer_balance_query_v1, name: 查询客户余额, description: 当用户询问账户剩余金额、可用余额、欠费情况时使用。本技能只支持只读查询不执行扣费或充值操作。, parameters: { customer_id: { type: string, description: 客户唯一标识可以从会话上下文中提取, required: true } }, output_schema: { balance: number, currency: string, updated_at: string }, version: v1, status: active }执行入口我一般用一个Python类来承接from typing import Any, Dict class BaseSkill: skill_id: str description: str def validate_input(self, params: Dict[str, Any]) - Dict[str, Any]: 参数校验返回清洗后的参数抛异常则终止调用 return params def execute(self, params: Dict[str, Any], context: Dict[str, Any]) - Dict[str, Any]: 执行技能逻辑返回符合 output_schema 的结果 raise NotImplementedError class CustomerBalanceQuerySkill(BaseSkill): skill_id customer_balance_query_v1 description 查询客户余额只读操作 def execute(self, params, context): balance query_balance_from_db(params[customer_id]) return { balance: balance[amount], currency: balance[currency], updated_at: balance[updated_at], }这里有几个细节值得说。第一validate_input和execute分开是为了让代理在调用前先做参数清洗避免脏数据直接进入业务逻辑。第二execute接收一个context参数里面放着会话状态、用户身份、环境信息技能内部可以根据这些信息做权限判断而不是只依赖代理传过来的参数。3.2 注册中心与动态加载技能定义好之后需要一个注册中心来统一管理。注册中心的核心功能是保存技能元数据、支持按关键词搜索、支持按状态过滤比如只让active状态的技能对代理可见。我常用的实现方式很轻量一个Python字典加一个文件扫描就够起步了。每个技能文件放在skills目录下文件名即模块名注册中心启动时自动扫描并加载import importlib import pkgutil import skills SKILL_REGISTRY {} def discover_skills(): for module_info in pkgutil.iter_modules(skills.__path__): module importlib.import_module(fskills.{module_info.name}) for attr_name in dir(module): attr getattr(module, attr_name) if isinstance(attr, type) and issubclass(attr, BaseSkill) and attr is not BaseSkill: instance attr() SKILL_REGISTRY[instance.skill_id] instance注册中心还要维护一个代理可见技能列表。不能把所有技能都暴露给代理否则当技能数量上来之后模型在超长技能列表里做选择反而会出错。我一般会按业务域把技能分组再根据会话的初始意图给代理只加载一个子集。3.3 让代理学会按需调用示例会话搭好最小实现之后最关键的一步是验证代理能不能正确地按需调用技能。我会做这样的一个示例会话来测试角色设定代理是一个客服助手可用技能包括查询订单、查询客户余额、创建工单、发送通知。用户输入我想看看我账户里还有多少钱。理想动作序列先判断这是查询余额的意图然后调用customer_balance_query_v1技能取出customer_id参数返回余额。如果代理调用错了技能第一步要看错误发生在哪个环节。是意图识别错了还是参数提取错了还是技能根本不可见。这三种情况的处理方式完全不同下面这张表是我排查时的常用对照错误类型典型表现优先检查项意图误判用户问余额却调用了工单创建技能描述里的触发条件是否清晰可用技能列表是否混杂了相近场景参数提取失败识别了技能但customer_id是空参数描述是否缺少来源说明context里是否有可提取的用户标识技能不可见代理说我没有查询余额的能力注册中心里技能状态是否active会话加载的技能分组是否覆盖该技能我自己的经验是超过七成的调用失败都出在技能描述和参数描述没说清楚而不是底层执行代码有Bug。所以每轮测试后我最先改的往往是元数据而不是执行逻辑。4. 技能评测与迭代从能用到好用4.1 评测集怎么构造代理技能不能只靠手工点几个例子就上线必须有可量化的评测集。我的做法是构造一个技能调用评测集里面每一条样本包含四个字段用户输入、期望调用的技能ID、期望的参数、期望的最终输出。举几个典型的评测样本[ { user_input: 我这个月的账单为什么比上个月多了80块, expected_skill: billing_detail_query_v1, expected_params: {billing_month: 2025-04, user_id: ctx.user_id}, expected_output: 包含账单明细和差异原因摘要 }, { user_input: 帮我把这批订单全部标记为已发货, expected_skill: batch_order_update_v1, expected_params: {order_ids: [], action: mark_shipped}, expected_output: 更新成功数量及失败列表 }, { user_input: 你好, expected_skill: no_skill, expected_params: {}, expected_output: 普通问候回应 } ]评测集的数量不用贪多我一般保持每个技能10到20条样本覆盖面比绝对数量更重要。关键要覆盖边界情况比如参数缺失、用户表达模糊、多个技能都能解释的歧义输入。4.2 常见失败模式与根因持续跑评测集一段时间后我总结出三种高频失败模式第一种叫技能名称诱惑。当技能名里带了业务关键词而用户输入也恰好包含这些词时代理会倾向于调用该技能哪怕语义上并不匹配。比如用户说我不想要订单了代理可能因为看到订单两个字就去调用查订单技能而用户的真实意图是处理退单。针对这种情况我通常在描述里加上否定约束仅当用户希望查看已有订单信息时使用不用于处理退款或退货请求。第二种叫参数来源幻觉。代理经常从用户原话里抓取参数但如果用户没直接说它就会自己编一个。比如某个技能需要的customer_id用户没有在对话里给过代理就从历史消息里硬找找不到就推测一个。这很危险。我的对策是在参数描述里写明来源路径比如从context.user_profile中获取不可凭空生成同时加一层validate_input的校验发现可疑参数就拒绝执行并提示重新提问。第三种叫多技能优先级混乱。两个技能都能部分满足用户需求代理随机选了一个。比如修改订单地址和查看订单物流用户在问我的订单能寄到新家吗时两个技能都可能被选中。这需要在描述里写明区分关键词比如前者强调要求修改后者强调查询当前配送状态同时可以在技能组里配置优先级让描述更精确。4.3 灰度替换策略技能迭代不是改完就全量生效我习惯用灰度策略。做法是新版本的技能先不替换旧版本而是让5%的用户会话使用新版本其余继续走旧版本。跑一段时间我一般观察三到七天对比调用成功率、参数校验通过率、下游任务完成率这三项指标都稳定再全量切换。这个灰度过程里日志要做好标记。每条调用记录都要带上skill_id和version这样后续分析才能精确定位是哪一版技能产生了问题。我吃过一次亏早期没有区分版本一个技能调了几十次都没发现问题后来一查日志线上同时混着两个版本的代码数据根本没法看到底是哪个版本出了问题。5. 真实项目里踩过的坑5.1 技能描述写了一堆代理却不调用我最早做技能库的时候特别认真地把每个技能描述写得很长各种细节都塞进去结果代理反而不调用了。后来我才明白描述过长会让关键信息被稀释。LLM在限定上下文中选择工具的行为本质上是在做一种机制化的匹配太长的描述反而让模型抓不住重点。我的改进方式是把描述拆成两部分核心触发描述控制在两到三句话先把什么时候用、什么时候不用说清楚然后把更详细的执行细节放到执行入口的代码逻辑里让代理在做选择时只需要看精简版描述即可。这个改动让技能调用准确率又提升了一截。5.2 技能互相干扰命名空间的设计失误有一次我做了两个技能一个叫发送站内通知一个叫发送短信通知。它们的场景明显不同但代理经常在需要发站内通知的时候去调短信接口。排查了很久才发现问题不在描述而在技能ID的前缀和内部实现里引用了同一个公共配置模块导致两个技能在注册中心里互相覆盖了部分配置。从那以后我规定每个技能必须完全独立命名空间自己的配置、常量、模板都放在自己的目录里不共享全局变量。哪怕两个技能确实要调用同一个底层服务也通过服务层封装来做不直接共用技能内部的模块状态。5.3 当技能数量超过50个时检索和路由怎么处理技能库做到50个以上后如果还把所有技能一次性暴露给代理模型的选择准确率会明显下降。我试过一次塞100个技能给代理结果简单场景都开始错乱。后来我引入了技能路由的概念在调用链上加一个轻量的路由层先根据会话的初始意图和用户画像从技能库里筛选出可能相关的10到15个技能再把这个子集交给代理做最终选择。路由层可以是一个简单的分类流程也可以是一个更轻量的分类模型。关键在于路由要宁可多给不要漏掉漏掉一个相关技能比多给几个无关技能更致命因为代理只要子集里还有正确选项就有机会选对一旦正确选项被过滤掉就必然失败。6. 把 agent-skills 做成一个团队协作资产6.1 技能评审和文档规范当团队成员都开始贡献技能时就需要一套评审规范了。我的技能提交检查表包含这几项技能有没有唯一的ID和版本号描述里有没有写明触发条件和禁止场景参数有没有标注来源和是否必填输出有没有匹配预定义schema有没有附上至少5条评测样本。这五条看着简单但能挡住绝大多数问题。我之前接手的某项目里有个成员提交的技能连参数schema都没写代理倒是也会调用它但调用后经常因为参数类型不匹配返回异常排查起来特别费劲。后来强制了评审流程这类问题基本绝迹。6.2 技能的自动测试和回归有了评测集和评审规范之后还缺一个自动化测试环节。我把技能评测做进了CI流程每次有技能改动就跑一遍全量评测集任何一条样本的调用结果发生变化都会拦截合并请求。这套做法对信心提升很大因为改动一个技能时最怕影响其他技能的调用行为自动回归恰好能暴露这种隐性耦合。6.3 从技能库到技能市场的扩展技能库成熟之后很自然会往技能市场的方向走。团队内部可以搭建一个技能共享门户每个技能挂上标签、说明、提交人和使用量数据。这样不同项目组可以直接复用已经验证过的技能不必每个项目都重新实现一遍订单查询、余额查询这类通用能力。我在一个多团队协作场景里试过这种方式效果很明显两个团队各自的代理系统在共享了基础技能包之后开发周期缩短了大约三分之一而且因为技能是被多个项目反复验证过的出问题的概率也低了很多。不过要留意一点技能一旦被多个团队共用变更流程就要更严格最好建立技能变更公告机制重大变更提前通知所有使用方。最后再分享一个实际操作的小技巧每次往技能库里加一个新技能先不要急着接进主代理。单独起一个测试环境只给代理挂这一个技能然后用20到30条真实风格的用户输入去跑确认调用率稳定在95%以上再合并进主线。这样做看起来多花了时间实际上省掉的是后续排查到底是哪个技能引入的问题的大把精力。技能库的维护慢就是快。