如果你最近在折腾 AI Agent大概率已经看过不少框架的 demo有的能自己写代码能上网查资料能操作浏览器。但 demo 归 demo一旦你想把这些能力真正组合成一个能稳定干活的智能体最先崩掉的地方往往不是模型本身而是技能管理——也就是 agent-skills 这一层。我前后接手过几套 Agent 项目从最早用一个超长 system prompt 塞满所有工具说明到后来把所有能力堆在一个脚本里到处写 if-else再到现在的技能化改造中间踩过的坑不算少。这篇文章把我沉淀下来的一套 agent-skills 设计思路、核心实现、编排方案和线上踩坑经验完整梳理一遍目标是让看完的人能够直接照着自己搭一套技能库而不是被各种花哨概念绕晕。1. agent-skills 到底解决了什么问题——先别急着写代码1.1 技能不是函数技能是智能体的“肌肉记忆”很多人第一次接触 agent-skills会把它理解成“把函数列表传给大模型”。这个理解不算错但太浅了。函数调用Function Calling只是大模型的一种输出协议它解决的是“模型表达意图”的问题而技能体系解决的是“意图如何被可靠执行”的问题。用一个生活化的类比你让一个实习生去“整理会议纪要”他会立刻知道要拿录音、看文档、提炼要点、按格式输出。这些动作不是靠临时翻规章制度才知道的而是他脑海里已经建立了“整理纪要”这个技能的完整路径。Agent 也是一样技能不是冷冰冰的函数签名而是把“何时该用”“用什么参数”“中间可能出什么问题”“输出成什么样”打包成一套完整的行为模式。我在项目里把 agent-skills 定义为一个技能 可被模型识别的能力描述 可执行的调用逻辑 明确的输入输出约定 失败兜底策略。四者缺一不可。1.2 没有技能体系时Agent 的真实表现有多糟糕我在早期一版方案里采用过“把所有能力说明全部塞进 system prompt”的做法。业务方给的需求是让 Agent 能查库存、下订单、算运费、查物流。一开始只有四五个功能prompt 还能扛得住。等到功能涨到第十几个的时候问题开始集中爆发模型开始“忘记”某些工具。工具说明太多上下文太长中间的工具描述会被模型选择性忽略越靠后的越容易被无视。相似功能互相打架。比如“按订单号查物流”和“按运单号查物流”模型经常选错因为两个描述在语义上太接近。参数幻觉严重。模型不是每次都能按照 JSON Schema 生成合法参数经常给你编一个不存在的订单号。升级一次 prompt 就全盘波动。你加一个新功能的描述原先表现稳定的老功能反而开始出错回归测试成本极高。这些问题本质上不是模型的错而是没有一个“技能抽象层”来替模型分担选择与调度的压力。agent-skills 这一层就是把“该选哪个能力”从模型临场判断变成一种结构化、可检索、可编排的系统决策。1.3 技能库、Prompt、工具调用三者之间的边界我经常被问到技能库和大模型 Function Calling 不冲突吗我现在用的框架里直接注册 tool 不就行了吗我的经验是工具调用是协议技能库是组织方式。两者的关系类似“函数”和“项目工程结构”的关系。函数语言本身就支持定义函数但你要管理几百个函数时还是需要分包、分层、写注释、做接口文档。agent-skills 就是那套工程规范。Prompt 适合描述“怎么思考”思维链、规则约束、角色设定。Tool/Function 适合描述“能做什么动作”给模型一个明确的输出接口。Skill 适合管理“动作的组合与沉淀”它可以把 prompt 片段、工具代码、前置检查、后置校验、重试策略全部封装成一个可复用的单元。所以在我的项目里技能不属于 prompt也不完全等同于 tool它是两者之上的一层封装。模型看到的是一份经过遴选后的技能清单和调用说明而不是一锅乱炖的大杂烩。2. 技能库设计我用的是三层结构2.1 第一层技能元信息——决定模型能不能选对这一层是 Agent 技能体系的“门面”也是我踩过最多坑的地方。元信息写得好不好直接决定模型选技能时准不准。我最终沉淀出一套字段核心记录在技能的注册清单里字段作用经验说明name技能唯一标识用动词 名词如query_express_by_tracking_no不要用模糊的check_statusdescription给模型看的自然语言说明必须写清“何时调用、何时不要调用、输入是什么、输出是什么”scenario_tags场景标签如order_query、aftersale用于预筛选input_schema入参 JSON Schema每个字段都要写 description枚举值也要写全output_schema输出结构模型会用这个判断下一步调用什么技能timeout_ms超时阈值每个技能的执行时间上限fallback_skill兜底技能失败后可以降级到哪个更简单的技能version版本号技能迭代记录用于灰度与回滚description 是这里面的灵魂。我给团队定的标准是一段优秀的技能 description 必须包含正例和反例。光写“查询物流信息”是不够的要写成类似这样当用户希望查询包裹运输进度时使用本技能。 输入参数 tracking_no 支持圆通、中通、韵达的单号。 注意本技能只用于已发货订单如果订单尚未发货请勿调用应改调 query_order_status 技能。这个“什么时候不要用”的负面说明能把很多误召回直接挡在门外。2.2 第二层技能执行体——把代码从 prompt 中解放出来执行体是技能真正干活的代码。我把它拆成五个阶段前置校验入参合法性检查。比如查询物流前先检查单号格式格式不对直接返回参数错误不浪费一次 API 调用。核心调用调用内部服务或第三方 API 获取结果。后置转换把原始返回加工成 Agent 容易理解的结构化文本。这一步非常重要因为上游接口返回的往往是给前端用的 JSON字段名是express_detail模型根本不知道是什么意思转换之后要变成物流轨迹如下这样直白的文本。结果包装统一返回 code、message、data 三层结构便于编排层判断。错误处理区分“可重试错误”和“不可重试错误”。超时、限流这类可重试参数错误、权限不足这类不可重试直接把原因返回给模型让它调整策略。特别提醒技能执行体里不要做大模型擅长的“理解类”工作。比如从一段长文本里抽取实体这种应该交给模型做而不是写在技能代码里。技能代码更适合做确定性的、可验证的事情。2.3 第三层技能编排层——从“选技能”到“组织技能”当技能数量超过二十个之后单靠模型自己从全量技能里选择会开始出现不稳定。我的做法是加一个轻量级的编排层负责三件事预筛选根据用户当前场景标签先把候选技能从全量过滤到一个小区间。比如判断当前会话属于“售后”场景就直接把库存管理、价格管理的技能排除掉。路由提示把过滤后的技能列表按照优先级排序在调用模型前注入 prompt。注意这里不是全量塞进去而是只给模型看“可能用得上的”技能可以显著降低选择噪声。执行链路记录记录每次调用选中的技能、入参、出参、耗时、是否回退方便后续复盘和调优。这个编排层可以用很轻的代码实现不一定要上重型流程引擎。我一开始以为 Agent 编排是什么高深的东西其实本质就是一个“缩小搜索空间”的过程。3. 从零实现一套可用的技能核心3.1 技能描述的标准格式为什么写不好描述Agent 就选错技能描述不是给程序员看的注释而是给大模型看的“使用手册”。很多团队把 API 文档直接粘进来当 description效果一塌糊涂。原因是 API 文档通常面向开发人员写的是参数类型和取值枚举但模型错过技能往往不是因为不知道参数怎么填而是不知道当前的用户问题可以映射到这个技能上。我总结出一套比较稳的描述写法触发条件第一句话必须写明“什么情况下调用”。例如当用户需要查询订单物流轨迹时调用本技能。排除条件第二段写明“什么情况下不要调用”。例如如果订单还未发货请调用 order_status 查询发货状态不要使用本技能。输入说明每个输入参数的来源和格式。例如tracking_no 由用户在聊天中提供如果用户只提供了订单号 order_id则必须先调用 order_to_tracking 技能转换。输出说明返回结果大概长什么样。例如返回物流轨迹节选若无轨迹则返回暂无轨迹信息。使用代价任何技能都有成本要么是 API 调用费用要么是执行耗时。我会加一句提示比如本技能通过第三方物流接口查询单次耗时约 500ms仅在用户明确询问物流时才调用。这段描述看着长但对模型来说是非常高质量的引导信息。我实测下来光把 description 按这个结构重写一遍技能命中准确率就从 72% 提到 89%。3.2 技能注册与检索从全量注入到按需加载早期我把所有技能描述全部注入上下文模型做选择。技能少时问题不大但技能到五十个以上时token 开销和选择准确率都会恶化。后来我改成两级检索第一级是规则预筛按场景标签、会话状态、用户显式输入做一次粗筛。比如用户发来一条包含“退款”的消息就把所有售后相关技能放进候选池。第二级是向量召回对候选池里的技能描述做 embedding和用户消息向量做相似度排序取 Top-K 个技能注入模型。这里有个容易忽略的细节向量检索召回的相似度阈值不要定得太死宁可多召回一两个无关技能也不要漏掉正确技能。相似度分数低并不一定代表不相关因为用户的表达千奇百怪而技能描述是相对规范的书面语天然存在语义鸿沟。我把阈值设得比较宽松召回率优先精确率交给模型在最终选择时把关。3.3 一个带参数的技能落地实例我举一个实际做过的技能例子“查询订单物流”。这个技能的上游接口是一个内部订单服务和一个第三方物流聚合接口逻辑是这样的用户输入订单号先判断订单里是否包含运单号如果没有运单号说明还没发货不能查物流如果有运单号就调物流聚合接口拿轨迹然后格式化输出。我给出的技能定义结构如下{ name: query_order_express, description: 当用户查询订单物流轨迹时调用。输入订单号或运单号若订单未发货则提示未发货不调用物流接口。, scenario_tags: [order_query, aftersale], input_schema: { type: object, properties: { order_id: {type: string, description: 用户订单号通常是纯数字}, tracking_no: {type: string, description: 运单号如 SF1234567890} }, oneOf: [{required: [order_id]}, {required: [tracking_no]}] }, output_schema: { type: object, properties: { express_company: {type: string}, track_list: {type: array, items: {type: string}}, latest_status: {type: string} } }, fallback_skill: query_order_status, timeout_ms: 3000 }对应的执行体伪代码大致是def execute_skill(params: dict) - SkillResult: # 1. 参数归一化 order_id params.get(order_id) tracking_no params.get(tracking_no) # 2. 前置校验 if not order_id and not tracking_no: return SkillResult.fail(param_errororder_id 和 tracking_no 至少提供一项) # 3. 由订单号查运单号 if order_id and not tracking_no: order order_service.get(order_id) if not order: return SkillResult.fail(biz_error订单不存在) if not order.get(shipped): return SkillResult.fail(biz_error订单未发货请调用 query_order_status 查询状态) tracking_no order[tracking_no] # 4. 调物流接口 try: track_info express_api.query(tracking_no) except TimeoutError: return SkillResult.retryable(物流接口超时) except RateLimitError: return SkillResult.retryable_delay(接口限流, retry_after2) except InvalidTrackingNoError: return SkillResult.fail(biz_error运单号不存在请核对后重试) # 5. 后置转换让模型直接能看懂 lines [f{node[time]} {node[description]} for node in track_info[nodes]] return SkillResult.success({ express_company: track_info[company], track_list: lines, latest_status: lines[0] if lines else 暂无轨迹信息 })这套代码看起来平平无奇但它把“业务规则”和“模型决策”清楚地分开了模型不需要知道“未发货不能查物流”这个规则它只需要根据技能描述决定要不要调用规则在代码里强制执行能极大地减少模型的“自作主张”。4. 技能编排实战让多个技能协作而不是互相打架4.1 顺序编排前一个技能的输出是后一个技能的输入做 Agent 功能时最常遇到的是链路式需求。比如用户问“我的订单用了优惠券吗”这个简单问题背后可能要走三步先用query_order_by_id查出订单详情如果订单关联了优惠活动再用query_coupon_detail查出优惠信息最后拼装返回。这其实就是一种顺序编排。实现时我优先依赖模型自身的能力也就是在多技能注入的情况下让模型自然地按顺序调用。但这里有一个先决条件每个技能的输出要让下一个技能能直接当作输入用。所以我在技能元信息里专门加了一个“output_schema”里面的字段名和描述尽量和“下一个技能可能需要的参数”对齐。比如query_order_by_id的输出里有coupon_id字段它的描述就要写明coupon_id 可用于后续查询优惠券详情。模型读到这句话就知道下一步该干什么。4.2 条件分支与回退技能失败不是结束是另一个开始技能调用的不确定性是常态。我在线上遇到最多的情况是模型信心满满地调用了 A 技能结果 A 技能返回一个业务错误提示这种情况其实应该用 B 技能。在没有回退机制的设计里模型只能把错误信息原样抛给用户体验很差。我的办法是在技能执行体里加上fallback_skill字段并在返回结果中用一个专门的字段suggest_switch_to告诉模型本技能不适合当前场景建议切换到某个技能。模型读取这个字段后可以直接发起新技能的调用不用等用户重新描述。举个真实例子用户说“帮我查一下为什么我的优惠券突然不能用了”。技能选择环节模型一开始命中了query_coupon_detail但该技能执行时发现这个优惠券已经过期而业务规则是“过期优惠券的补偿方案需要走售后流程”。于是技能返回{ code: BIZ_RULE_HIT, suggest_switch_to: create_aftersale_ticket, message: 优惠券已过期如需补偿请创建售后工单 }模型读到后直接调用create_aftersale_ticket用户整个过程无感知不会多经历一次“这个问题我处理不了请转人工”的挫折感。这种主动的技能切换机制让我那些 Agent 的体验好了好几个档次。4.3 并发技能与资源冲突Agent 同时调用多个技能时的稳定性问题当技能编排从串行走向并发后新问题来了。一些 Agent 框架允许模型在一次响应中得到多个 tool call然后同时执行。听起来很高效但实际会遇到两类麻烦资源竞争两个技能同时访问同一个数据库连接池把连接池占满双双超时。事务不一致一个技能先更新了订单状态另一个技能读取旧状态做判断产生脏读。我现在采取两条措施第一按技能“资源域”分组不让同域技能并发。比如订单查询和库存查询都属于“订单域”模型即使同时触发编排层也会把第二个技能放进队列等第一个技能执行完再执行。跨域的技能比如“订单查询”和“天气查询”可以放心并发。第二给写操作技能加“串行闸口”。凡是包含数据库写入、订单状态变更、工单创建这类副作用的技能全部走同一把分布式锁避免同一条订单被两个并发技能同时改。这些措施不需要多么复杂的框架一个内存队列加一把 Redis 锁就能实现大部分场景但带来的稳定性提升非常明显。5. 我把技能库跑上线之后踩过的坑5.1 技能描述“看起来合理”但实际一测就翻车写技能描述时我犯过的最严重错误是“把理想行为写成了描述”。比如某数据查询技能底层接口其实只能查最近三个月的订单但描述里写的是“查询用户订单信息”。结果模型完全不设防地调用它用户问半年前的订单技能返回空结果模型还要硬着头皮编一个“没有找到您的订单”实际上数据根本不在接口范围内。后来我统一在描述里写清楚了“数据范围”和“已知限制”本技能仅能查询近 90 天以内的订单 如果用户询问更早的订单请直接告知暂不支持查询并建议用户前往订单中心查看。这段限制写在描述里之后模型不会再做无谓的调用回答也老实了很多。技能描述里写限制条件看着像在“削弱”技能能力实际上是保护整体体验不崩坏。5.2 技能版本演进的兼容性难题技能是会迭代的。我遇到的一个典型场景是某个技能改了入参格式把user_id字段改成了uid技能库里的定义也同步更新了但线上跑着的会话里模型上一轮生成的「参数携带说明」还是老的记忆新技能就拒绝执行。连续报错好几次用户感知很差。我的经验是两条技能入参尽量向后兼容。即使是内部技能也不要轻易删除字段名。可以把旧字段名保留为 alias内部做一次归一化。技能版本增加时需要显式告知模型。在每次会话的技能注入列表里带上skill_version信息模型输出调用参数时如果发现版本变化会倾向于重新从技能描述里提取参数而不是沿用老记忆。5.3 技能多了之后怎么评估好坏技能库不是越多越好而是越“准”越好。我建了一套简单的量化评估指标每周跑一次指标含义我的目标技能命中率模型最终选中的技能是否是正确的那个 90%技能调用成功率技能执行后返回 codesuccess 的比例 95%回退率是否经常发生 fallback_skill 切换 5%平均链路长度完成任务大致需要调用几个技能越低越好无效描述率模型选了个技能但最后没用到它的输出 10%把评估结果按周维度和版本维度对比能很快发现是哪个技能描述退化、哪个接口稳定性下降。这项基本功很多人不做导致技能库最终变成一堆没人敢动的“技术债”。6. 下一步扩展我认为最值得投入的三个方向技能库跑稳之后我一直在思考如何继续扩展价值。有几个方向是我正在尝试的分享出来供你参考。第一个方向是技能自动发现与半自动生成。现在的技能还需要人肉注册、写描述成本并不低。我在实验一种半自动方式用一个“技能挖掘器”定期扫描系统里的日志找出那些“用户反复提问但 Agent 总是答不好”的会话片段把它们聚类生成新技能的雏形描述再由人来确认。这相当于给技能库做了个“需求雷达”。第二个方向是技能质量评估的离线仿真。我准备搭一套离线评测集把历史真实用户问题沉淀成用例每次技能库改动后先跑一遍离线评测再决定是否上线。这样可以避免把线上测试当回归 test能把模型选错技能的代价降到最低。第三个方向是跨 Agent 技能共享。如果你手上不止一个 Agent每个 Agent 都用各自的技能库维护成本会成倍增加。我目前的做法是把技能定义抽成独立的注册中心不同 Agent 只保留自己需要的技能可见子集。这样既能独立迭代又能沉淀共享能力。以上三个方向前两个偏向工程效率第三个偏向组织和成本结构。对我来说agent-skills 的核心价值一直不是“炫技”而是让 Agent 的每一项能力都变得可维护、可度量、可在团队里高效协作。技能库的稳定性永远决定了智能体能力的下界这一点只有真正在生产环境里跑过的人才会深有体会。