做 AI Agent 应用的人，最近一定绕不开一个词：skills。我最早接触这个概念，是在给某个内部智能体项目做大模型调用封装的时候。当时团队面临一个很现实的问题：模型能力再强，也不可能内置所有业务逻辑，总不能每次都写死一套固定的工具调用代码。后来我们把技能体系独立出来，做了一个代号 agent-skills 的模块，才真正解决了“让智能体像积木一样拼装能力”的问题。这篇博文就围绕这套机制展开，从整体设计、技能定义、核心链路、常见踩坑到多技能协同，一层层拆给你看。适合正在做智能体平台、自动化工作流或者想给现有 AI 应用加“手脚”的开发者参考。
市面上很多项目把 Agent 做成了“一个循环 + 一堆工具”，看起来能用，但规模一上来就崩：技能之间互相打架、参数抽取随心所欲、执行完没有反馈、想复盘也不知道从哪下手。agent-skills 的思路恰恰相反，它把技能当成一等公民，用一套标准化的注册、路由、执行、评估机制来管理，让每个技能都可发现、可复用、可度量。这套设计不绑定某个具体模型，也不依赖某个特定框架，理论上适用任何以语言模型为核心的自动化场景。
1. 整体设计思路拆解
1.1 为什么 Agent 需要一套“技能”体系
Agent 的本质是“感知-决策-行动”的闭环。大模型负责感知和决策，行动则需要外部能力来承接。如果行动层是一堆散装函数，决策层就只能在“瞎猜”和“硬编码”之间走钢丝。
我见过不少团队的早期方案：把工具函数丢在系统提示词里，让模型自己去调。项目初期确实跑得通，但很快会遇到三类问题。第一是描述不一致，同一个技能的说明散落在不同提示词模板里，改一处漏一处。第二是参数不可控，模型偶尔会凭空捏造参数，比如把日期格式从 YYYY-MM-DD 擅自改写成 MM/DD/YYYY。第三是无反馈，工具执行完只有最终结果，没有中间日志、没有耗时、没有失败原因，出问题只能靠肉眼排查。
agent-skills 要解决的就是这三件事。它把“技能”抽象成一套带元数据的模块：技能名字、功能描述、参数规范、执行逻辑、返回结构、异常码。模型不需要自己发明调用方式，只需要在给定技能列表里选一个最合适的，然后按规范填参数。这样既能发挥大模型的理解能力，又不会让它“自由发挥”到失控。
另外还有一个容易被忽略的维度：技能的生命周期。业务逻辑会变，接口会升级，旧的调用方式不能立刻作废。有了技能注册中心，每个技能可以维护版本历史、灰度配置、启用状态，需要回滚时一键切换，而不是去改一大段提示词。
1.2 技能系统的核心组成与关键选型逻辑
一个完整的技能系统，我拆成了五个部分：技能注册中心、技能描述库、路由选择器、执行沙箱、评估反馈模块。
注册中心负责登记所有可用技能，相当于“技能户口本”。每个技能在接入时先在这里备案，拿到唯一的技能 ID。描述库存的是模型能看到的元数据，包括一句话说明、适用场景、参数 schema、返回值格式。这里有个关键点：描述库存放的内容最终会拼进大模型的上下文，所以必须既精确又简洁，不能把实现细节都塞进去。
路由选择器承担“该选哪个技能”的决策。实践中我试过纯语义 embedding 匹配、规则关键词匹配、大模型直接选择这几种路线。纯 embedding 匹配的好处是快、便宜，但技能越加越多，相近技能之间的区分度会下降。大模型直接选择更准确，但会多一次推理延迟。我的最终方案是两段式：先用轻量的关键词和 embedding 做粗筛，拿到候选技能列表，再交给主模型做最终决策。这样既保证准确率，也控制成本。
执行沙箱解决“技能运行时的安全和隔离问题”。如果技能只是调用内部 API，直接在进程里跑没问题。但如果技能要执行任意代码、读写文件、访问外网，就必须做隔离。agent-skills 给每个技能配置了独立的执行权限策略，比如只允许访问某个域名的接口、只允许读某个目录的文件。超时也做了硬控，单技能默认 10 秒超时，防止某个慢接口把整个 Agent 流程拖死。
评估反馈模块是技能系统持续进化的动力。每次技能调用都会记录结果、耗时、错误信息，然后回流到评估层。如果一个技能频繁被选中但执行失败率高，路由选择器会自动降权，或者给模型提示“该技能近期不稳定，谨慎选用”。
2. 技能定义与注册机制
2.1 技能描述规范：从自然语言到结构化元数据
技能描述是整个系统中最重要的“接口文档”。大模型不看你的代码，只看你写给它的描述。描述写得好，调用准确率就高；描述写得烂，再强的大模型也会用错。
我用的描述规范是 JSON Schema 加自定义扩展字段。JSON Schema 的好处是生态成熟、校验工具多、LLM 也容易理解。除了 schema 本身，我额外加了几个字段：trigger用于触发条件描述，when_to_use说明什么时候优先使用，when_not_to_use说明什么时候别用，examples放一两个典型调用示例。
{ "skill_id": "fetch_order_status", "display_name": "查询订单状态", "description": "根据订单号查物流和履约状态", "when_to_use": "用户询问订单是否发货、签收或异常时使用", "when_not_to_use": "用户问历史订单列表时使用 search_orders，不要用本技能", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "订单号，通常是 10 位数字加字母的组合" } }, "required": ["order_id"] }, "return_schema": { "type": "object", "properties": { "status": { "type": "string", "enum": ["created", "paid", "shipped", "done", "cancelled"] }, "logistics": { "type": "array", "items": { "type": "string" } } } } }这里有一个值得注意的细节：when_not_to_use可能比when_to_use更重要。模型出现选择错乱，很多时候不是因为不知道什么时候该用，而是不知道什么时候不该用。举个例子，用户问“最近一个订单到哪了”，模型可能误选“查询订单状态”，实际上应该调用“获取最近订单列表”拿到最近的 order_id，再调用查订单状态。我在描述里显式写了“不要用”，之后这种错误明显减少。
参数描述也很有讲究。我发现，模型对参数描述里的单位、边界条件、示例值特别敏感。比如order_id如果只写“订单号”，模型可能把带空格或连字符的文本也传进来。写成“通常是 10 位数字加字母的组合”，并配一个示例，模型抽参就会规整很多。
2.2 注册与版本管理：让技能可发现、可更新、可回滚
技能注册不只是“登记一下”，它决定了系统能不能长期演进。我在 agent-skills 里设计了注册中心与配置中心联动，而不是让开发改代码后手动同步。
注册流程是这样的：开发者在代码里定义一个 Skill 对象，包含上面讲的描述文件和对应的执行函数。注册中心读取后，分配版本号，更新描述库。每次注册都会保留历史版本，如果新版本效果不好，可以在管理端一键切换回旧版。这里的版本切换不是改提示词，而是直接换掉描述库里指向的实现，对模型来说是透明的。
另一个很重要的机制是“上下线灰度”。某个技能如果在新场景下不稳定，我不会直接删掉，而是先把它标记为“低优先级”。路由选择器仍然能看到它，但在候选技能排序时会把它放后面，只有当其他技能都不匹配时才可能轮到它。这样给业务方一个缓冲期，不至于因为技能下架导致 Agent 突然无法处理某类请求。
版本管理还需要配套一个变更记录表，至少要记录：变更时间、变更人（或来源任务）、变更内容、影响范围、回滚标识。这个表在出问题时拯救过我好几次，不然全靠 Git 历史去翻，效率太低，而且代码提交信息根本不写“改了哪个技能”。
3. 核心链路与实践要点
3.1 技能调用主流程：意图识别、参数抽取、匹配路由、执行、结果回填
技能调用的完整链路，可以拆成五个环节：意图识别、参数抽取、匹配路由、执行、结果回填。看似简单，但每个环节都有坑。
意图识别经常被和技能路由混为一谈，但实际是两件事。意图识别判断“用户想要什么”，技能路由判断“哪个技能能完成这个目标”。在我的设计里，意图识别由主模型在一次推理中顺带完成，不单独调一次请求。如果单独做意图分类，会多一次延迟，而且在简单场景里杀鸡用牛刀。
参数抽取是关键难点。模型抽取参数的准确性，直接影响技能能否执行成功。我给了一个“双校验”策略：先让模型抽参，然后用 JSON Schema 校验器做合法性校验；对于枚举型字段、日期字段、数字区间字段，再做一次显式的规则校验。校验失败时，不要直接报错，而是把校验错误信息回传给模型，让它重新抽一次。这个“失败回循环”能显著提升成功率。我测量的数据里，首次通过率大概 78%，加了回传纠错后能到 94% 以上。
匹配路由的顺序建议是：粗筛 + 精排 + 兜底。粗筛用轻量级方式（比如 BM25 或 embedding 相似度），把候选技能范围从几十个缩小到三五个。精排把这几条候选技能描述交给主模型，让它结合用户请求做最终选择。兜底则是在没有技能匹配时，给出一个默认行为，比如“转人工”或“回复未知指令”，绝不能留空。
执行阶段除了沙箱隔离，还有一件容易被忽略的事：结果回填的格式。技能返回的原始数据往往很“程序化”，比如状态码、原始 JSON 字段，直接拼回上下文会让模型困惑。我加了一层 result adapter，把执行结果统一转成“人类可读摘要 + 结构化数据”的格式。例如“查询订单状态”返回的结果：
执行成功。 当前订单状态：已签收。 物流轨迹最近一条：2025-01-12 10:23 包裹已由本人签收。 结构化数据见下（供参考）：...这样模型在后续多轮对话里才能自然地引用这些信息，而不是生硬读字段名。
3.2 参数校验与安全执行：给技能加“护栏”
技能一旦暴露给外部用户，就必然会遇到对抗性输入。给技能加护栏，不是不信任模型，而是不信任外部世界的不可预测性。
参数校验有三层：格式校验、业务校验、安全校验。格式校验用 JSON Schema 就能做。业务校验需要看上下文，比如一个查询订单技能，订单号格式正确，但订单不属于当前用户，这时候必须拒绝。安全校验主要是指“不要让技能执行超出设计边界的操作”，比如一个“发邮件”技能，必须校验收件人是否在白名单内，或者至少校验目标域名是否内部域名。
我在 agent-skills 中把安全校验设计成每个技能的守卫函数（guard）。守卫函数在参数校验之后、执行逻辑之前运行，返回放行或拒绝。拒绝时返回明确原因，模型会把这段原因加工成用户能理解的提示，而不是暴露内部细节。
超时和限流也得提前设计。技能执行有超时时间，整条 Agent 链路有一次总的超时预算。比如说每次任务的总超时是 30 秒，那么单个技能的调用必须在 10 秒内完成，留出缓冲给模型的推理时间。如果某个技能频繁超时，优先怀疑技能内部逻辑，比如第三方 API 没有设置 client timeout，或者做了串行请求。遇到这类情况，我通常会在技能内部把下游请求改成并发，或加一层本地缓存，而不是盲目调大超时。
3.3 可观测性与评估闭环：怎么判断技能好不好
技能系统的可观测性，第一步是日志要全。我要求每次技能调用至少记录以下字段：技能 ID、版本号、触发用户请求、模型解析出的参数、路由置信度、执行时长、返回结果摘要、错误类型、耗时分布。日志统一进存储，方便按技能汇总审查。
第二步是定义质量指标。我目前用的核心指标有三个：使用率、成功率、修正率。使用率反映技能被模型选中调用的频率；成功率反映执行过程是否正常；修正率反映参数抽取失败的次数占总调用次数的比例。这三个指标组合起来，能快速暴露一个问题：某个技能是不是一直“被选中但用不好”。
有段时间，agent-skills 里某个数据查询技能的使用率很高，但成功率不到 60%。查看日志发现，用户经常带着模糊的时间范围提问，模型抽参会把“上周”解析成具体日期，但初始化模板里的默认日期是 UTC 时区，和业务时区差了好几个小时。这不是参数格式问题，而是业务规则没写进描述里。后来我在参数描述里加了“如果用户提供相对时间，请基于上海时区当前时间计算”，成功率直接从 61% 拉到了 88%。
评估闭环还包括定期回放。我会把过去一周的真实用户请求抽样，重放给技能路由层，看“理想技能选择”和“实际技能选择”的差距。做法很简单：让另一个模型对同一请求标注它认为应该调用哪个技能，然后和系统实际路由结果做对比。不一致的样本，定期分析原因，是描述歧义、参数缺失，还是路由排序优先级问题。
4. 常见问题与排查技巧实录
4.1 技能匹配错乱：模型总是选错技能
这个问题的根源通常不在模型能力，而在技能描述互相干扰。比如同时有“查订单详情”和“查物流信息”两个技能，描述里都可能出现“查订单”。模型很难分辨。
我的排查套路是三步。第一步，把用户请求和两个技能的描述同时拿给模型，问“这两个技能最核心的区别是什么”，看模型自己怎么说。如果模型也说不出区别，说明技能边界确实模糊。第二步，给其中一个技能加上when_not_to_use，显式说明“如果用户关心的是运输轨迹，请使用查物流信息”。第三步，做一组小样本对比测试，把常混淆的请求做成评测集，每次改动描述后跑一遍，看准确率变化。
有时问题也出在路由粗筛阶段。粗筛的排序分数如果差异很小，精排阶段会把几个候选一起丢给模型，模型看到相似度很高的几条，容易被描述更详细的技能带偏。我会在粗筛阶段提高阈值，宁可漏召回，也不要噪声候选。漏召回还能靠兜底逻辑兜住，噪声候选则会直接误导模型。
4.2 参数抽取漂移：同一个字段今天能抽明天不能
参数抽取漂移，直接原因是模型版本更新或提示词调整，深层原因往往是描述里的边界没写清楚。我见过最典型的案例是时间范围抽取。用户说“查一下这周的数据”，模型有时候把“这周”解析成周一到今天，有时候解析成最近 7 天。两种解析方式在周一和周日差异不大，在周三就完全不同。
解决漂移的办法是把“可枚举的解析策略”写进描述里。比如：“当用户说‘这周’，一律理解为本周一 00:00 到当前时间；当用户说‘最近 N 天’，一律从昨天开始往前推 N 天，不包含今天。”这类规则写清楚之后，模型输出的结果一致性会大幅提升。
另一种漂移是模型对枚举值的选择不稳定。比如技能有一个sort_order字段，可选值asc和desc。用户说“按时间正序”，模型有时能正确映射，有时反而选desc。对这种字段，我建议不要依赖模型记忆映射关系，而是在技能代码里做一个显式转换函数，无论模型传什么值，都按一套预设关键词表统一映射。
4.3 执行超时与资源占用：技能把整个 Agent 卡死
技能执行超时是上线初期最容易炸的问题。有一次，某个文件处理技能在压测环境中成功把整台服务器的 CPU 打满，原因是它调用了某个第三方压缩库，对超大文件的处理是纯同步的。那次之后，我把所有技能的执行逻辑都要求写成“可中断”的形态，即内部循环必须定期检查取消信号。
超时阈值建议分层设置。外部 API 类技能，单次调用超时 3-5 秒；数据聚合类技能，可以给 10 秒；任何技能禁止在内部做无界循环或无界内存操作。同时要为每个技能设置独立的并发限制，防止多用户同时触发重负载技能导致资源耗尽。
排查超时问题时，不要只关注技能本身。模型在调用技能前要多轮推理，如果主模型响应慢，也会让用户感觉整个 Agent 卡住。我在可观测性面板里把“模型推理耗时”和“技能执行耗时”分开展示，这样能快速定位到底卡在哪一层。
4.4 评估指标失真：成功率很高但用户仍不满意
成功率这个指标，只能反映技术执行结果，不能反映用户满意度。比如“查询天气”技能，执行成功率 100%，但如果用户在北京问“明天要穿什么”，技能返回的是天气数据而不是穿衣建议，用户会觉得答非所问。
这种失真通常来自“技能边界和用户预期”的错位。解决方式有两种：一种是在技能描述里明确输出的颗粒度，如果技能只负责返回天气原始数据，那就限制模型不要再做过度加工；另一种是增加一个后处理策略，让模型在拿到结果之后，判断是否还需要调用其他技能来补全。以穿衣建议为例，正确路径应该是查天气后，结合天气数据生成建议，而不是查完就结束。
评估指标也要增加一个“结果可用性”采样。我会随机抽一部分成功日志，人工看模型回填给用户的回答是否真正有信息量。这个指标不能自动化完全替代，但定期的人工抽检能发现很多“数字好看、体验很差”的隐蔽问题。
4.5 多技能协同时的冲突：技能之间互相覆盖结果
技能协同冲突是复杂度上来之后的常见问题。表现是：A 技能先返回了一个结果，B 技能随后又返回一个字段名相同但含义不同的结果，模型在生成最终回答时不知道以哪个为准。
我在 agent-skills 里引入了“输出字段命名空间”机制。每个技能定义自己输出的字段名，并要求在技能内做前缀命名，或者统一在结果里带上 skill_id。比如get_order_status输出{ "order_status": "shipped" }，另一个get_inventory_status输出{ "inventory_status": "low" }。字段不重名，模型就不容易混淆。
更深层的冲突是“技能执行顺序”问题。任务需要多个技能串联时，后一个技能可能需要前一个技能的输出作为参数。我在描述库里专门增加requires字段，声明该技能依赖哪些前置技能的结果。路由层看到requires之后，会主动检查前置技能是否已经调用，如果没调用，就先安排前置技能执行。这个依赖编排做得好，多技能场景会自动变得有序，而不是靠模型临场发挥。
5. 多技能协同与复杂任务编排
5.1 任务分解与技能组合：让复杂任务自动“化整为零”
单个技能解决单一问题，复杂任务要解决的是“多个问题的组合”。比如用户问“帮我看看上周各区域的销售数据，并找出增长最快的三个区域，然后生成一个简短汇报”。这个任务至少涉及三个技能：查销售数据、区域筛选聚合、生成汇报文本。
我在 agent-skills 里的处理方式是“计划先行”。首轮推理时，模型先输出一个任务计划，列出需要执行的步骤以及每个步骤对应的技能。这里注意：计划里的步骤不要写得太细，太细会占用上下文，也容易出错；只要写清楚执行顺序和依赖关系就够了。
plan = [ {"step": 1, "skill": "query_sales_data", "params": {"time_range": "last_week", "granularity": "region"}}, {"step": 2, "skill": "aggregate_regions", "params": {"metric": "growth_rate", "top_n": 3}}, {"step": 3, "skill": "generate_report", "params": {"format": "short_" + "brief"}} ]计划生成后，由执行引擎按依赖顺序调用。每步技能的返回结果会保存到一块共享内存里，作为后续技能的上下文。这里有个铁的纪律：后续技能只能看到前置技能的“结果摘要”或“指定字段”，不要把完整原始数据灌进去，否则上下文会被撑爆。
任务分解的关键在于“拆到什么粒度”。拆太粗，一个计划步仍然是个复杂任务，技能能力不够；拆太细，模型要维护十几步的状态，容易在中间环节迷失。我通常建议一个复杂任务拆成 3-5 个步骤。如果超过这个数，优先怀疑是不是技能本身设计得过大，应该拆成更小的原子技能。
5.2 长上下文管理与记忆策略
多技能协同必然带来上下文增长。每次技能调用原样塞回结果，几轮下来上下文就爆了。我的策略是“摘要替换 + 关键信息保留”。每步执行之后，用一段 50 字以内的摘要概括结果，并单独保存关键字段到结构化存储中。后续技能需要某个字段时，直接从存储里取，而不是重新解析冗长的对话历史。
给每个技能设计“输入消费视图”是一个好习惯。名义上技能能访问全部上下文，实际只消费它 declared 的参数。我在技能框架里加了一个context_view参数，显式声明该技能需要从历史中看到哪些信息，其他信息在调用时不让模型接触到。这不仅减少 token 消耗，还能降低干扰。
长任务还需要处理“记忆漂移”。当任务执行到第 4 个技能时，模型可能忘了第 1 步的结果。我的做法是每执行完一个阶段，就把当前的累计摘要重新整理一遍，作为下一阶段的“状态卡”固定放在上下文开头。状态卡里的信息不是自然语言流水账，而是结构化的键值对，模型一眼就能找到需要的东西。
记忆策略要区分短期记忆和长期记忆。短期记忆在任务执行期间有效，任务结束后清空；长期记忆是用户画像、常用参数偏好，存存储后按需注入。这两个不能混用，否则模型会自动把本次任务的细节当成用户长期偏好，下次提问时反而产生干扰。
6. 优化扩展与最终建议
6.1 技能复用与组合重构：从“能用”到“好用”
技能系统的价值上限，取决于技能复用的效率。我见过很多团队把业务逻辑一股脑写成单个“多功能”技能，参数列表越拉越长，最后模型根本不知道先填哪个参数。
更合理的做法是把技能拆成“原子技能”和“复合技能”两层。原子技能做一件事，参数少，职责明确，比如send_email、extract_keyword。复合技能则通过编排多个原子技能完成一个较高的目标，比如weekly_report内部调用query_data、aggregate、generate_markdown三步。复合技能对模型暴露的接口可以简化，参数由内部编排逻辑自行消化。
这套设计最直接的好处是：新业务接入时，很可能不需要新写技能，只要把已有原子技能按照新顺序组合一次就行了。比如从“周报汇报”扩展到“月报汇报”，可能只需要调整时间参数和聚合维度，完全不用重新开发。
复合技能的编排逻辑要写在代码里，而不是写在提示词里。写在代码里，可以测试、可以 debug、可以写单测；写在提示词里，模型每次要重新“理解”整套流程，出错率和耗时都会上升，不可控。
6.2 从零开始搭建的最小实践路径
如果你想在项目里落地一套技能体系，不一定要像我一样一开始就搞全套。我建议最小可行路径是这样：
第一步，先定义 3-5 个核心技能，只写描述文件和执行函数，不搞注册中心、不搞版本管理。跑通“模型选技能 + 调参数 + 执行 + 回填”的最小闭环。这个闭环能跑通，说明基础链路没问题。第二步，引入一个简单的评估集，准备 20-30 条典型请求，每次改技能描述后跑一遍回归。这个评估集会成为你后续所有优化的锚点。第三步，在技能数量超过 10 个或需要多人协作时，再搭建注册中心和版本管理，这样才不会因为过早优化而陷入配置复杂度。
关于框架选型，我的建议是“先手动，后框架”。先用原生调用把技能链路做出来，理解每一步的 token 成本和延迟分布，再考虑用无需自己实现的编排框架。直接用框架虽然有脚手架，但出了问题你会分不清是框架 bug 还是你的设计问题，排查成本反而更高。
我在实际项目里还有一个习惯：每个技能必须配一个“反例测试”。即编写一个“不应当触发该技能”的输入样本，跑一遍确认模型不会误选。比如send_email技能的反例就是“请帮我查一下邮箱收件箱”，这两者边界模糊，最容易误判。反例测试每次随评估集一起跑，能持续防止技能描述改动导致的回归退化。
6.3 我踩过几次坑之后的个人经验
这篇文章写到最后，想再分享几点个人经验。
第一，技能描述永远不要“一次写到位”。它需要根据真实日志反复迭代。我几乎每周都会调整几个技能的描述，来源都是评估集里失败的样本。每次只改一个点，改完就跑回归，不要同时改多个技能的描述，否则根本不知道是哪个改动起了作用。
第二，先处理异常再优化性能。很多团队刚开始就把精力花在“让技能响应更快”上，但这套系统早期最大的问题通常是“模型没用对技能”或“参数抽错”。性能优化是末期的事情，准确率才是地基。地基不牢，速度再快也没用。
第三，不要把缓存和记忆混为一谈。缓存是技术手段，用于减少重复计算；记忆是产品能力，用于跨会话保持信息。我在早期设计里把技能结果缓存当成记忆用，结果在线服务时出了“旧数据被当成新事实”的错。后来严格区分，技能结果缓存只服务同一次会话内的重复调用，长期信息统一走用户画像存储。
第四，技能系统的可观测性，要在一开始就预留好，不是后期补的。哪怕你目前只有 3 个技能，也要把调用日志、耗时、错误码、参数字段记录下来。等技能数量到 50 个时再想补日志，几乎不可能，因为老版本跑过的历史数据已经丢了。
agent-skills 这套设计，本质上是在大模型的自由度和业务的确定性之间搭一座桥。模型负责理解、决策、表达，技能负责执行、反馈、兜底。这个桥搭得稳不稳，直接决定了智能体应用能走多远。希望这篇项目拆解能给你一些可复用的思路，也欢迎带着你的踩坑经历来交流。
