这些年做大模型应用，我越来越觉得“agent-skills”这个说法比“prompt engineering”更贴近真实战场。模型本身的能力边界其实很清晰，真正让一个智能体从“能聊天”变成“能干活”的，是它手里到底攒了多少个设计扎实、边界清楚、可复用、可观测的技能。你可以把技能理解成智能体的一双手：模型负责思考，技能负责执行，思考再聪明，手上没活儿也白搭。这篇文章我结合自己做 agent-skills 技能库的完整过程，聊聊技能到底怎么设计、怎么落地、怎么排查，适合正在做智能体应用、被工具调用不稳定折磨过的同学参考。
1. 为什么“技能化”突然成了智能体工程的焦点
先说一个我自己的感受：早期做 Agent 应用，大家拼的是模型推理能力，谁家模型更会“想”，谁的效果就更好。但做到后面会发现，单靠模型自由发挥根本撑不起一个稳定产品。用户问同一个问题，模型今天调这个工具，明天走那条分支，后天干脆自己编一个答案。真正能让系统变得可控的，不是更强的推理，而是把“动作”提炼成标准化的技能，让模型在有限选项里做选择。
1.1 从“让模型变聪明”到“让系统变可靠”
这里有个很关键的心态转变：不要让模型自己去发明调用方式，而是把调用方式固化成可注册、可发现、可校验的技能模块。agent-skills 的核心价值，就是给智能体一份“能力清单”，清单里每一项都写清楚：这个技能是干什么的、接收什么参数、返回什么结果、失败时会怎样。
这样做的好处非常直接。第一，模型只需要做“分类+匹配”，不需要理解每个后端系统的细节；第二，技能可以单独测试，哪个技能坏了就修哪个，不用整个链路一起排查；第三，技能可以被多个 Agent 复用，业务方 A 开发好的技能，业务方 B 可以直接挂载，不用重复造轮子。
我自己踩过一个大坑：最开始我们让模型直接调用内部 API，prompt 里塞了十几页接口文档。结果模型经常把参数名写错，或者把枚举值传成自由文本。后来把所有接口改造成技能，统一封装成带 schema 描述的调用单元，调用成功率直接从六成多拉到九成以上。这个数字对比，比我预想的还要夸张。
1.2 一次技能定义带来的连锁变化
把工具改造成技能，不只是“多包一层”那么简单，它会引发一系列连锁变化。首先是权限模型变了：以前模型只要拿到 API Key 就能调用一切，现在每个技能都有自己的授权范围，你可以精细控制哪个 Agent 能用哪个技能，安全边界清晰很多。
其次是可观测性变了。技能天然是一个个独立的执行单元，每个技能的调用次数、成功率、平均耗时、失败原因都可以单独埋点统计。哪个技能是高频热点，哪个技能经常报错，一眼就能看出来，这比在日志里海捞自然语言对话高效太多。
最后是迭代方式变了。以前优化一个功能要改动整个 Agent 的 prompt，风险很大；现在只需要优化某一个技能的描述或参数校验逻辑，单独发版验证就行。技能库慢慢沉淀成整个团队共用的“能力资产”，新人上手也快，看技能清单就能知道系统能做什么。
1.3 技能与工具、插件、工作流的边界
很多同学会问：技能、工具、插件、工作流，这四者到底什么关系？我自己的划分逻辑是这样的。工具是最底层的原子能力，比如“发送 HTTP 请求”“读写文件”“调用数据库”；技能是“带着语义和约束的工具封装”，比如“查询今日天气”“生成周报文档”；插件通常指一组相关技能的打包发布形态；工作流则是多个技能按固定顺序编排而成的流程。
这几个概念经常混着用，但工程上最好把边界定清楚。agent-skills 解决的是“模型该怎么用能力”的问题，它处于工具和工作流中间：比工具多一层语义和参数契约，比工作流少一层固定编排。这样模型既不用面对过于底层的实现细节，也不会被工作流绑死执行顺序，能在技能之间自由组合，反而更容易应对用户千奇百怪的真实需求。
2. 一套能落地的 agent-skills 设计方法
很多人觉得技能设计很简单，写个名字加描述就完事。实际上，一个技能要能被模型稳定识别、被系统安全执行、被维护者轻松迭代，需要一套完整的设计规范。我把自己沉淀下来的方法拆成几个维度慢慢讲。
2.1 技能描述：决定调用成功率的第一道关口
在智能体场景里，描述写得不好，模型根本不会调你这个技能，或者调错技能。描述的关键不是“解释功能”，而是“帮助模型做决策”。你需要用两三句话说明：这个技能在什么场景下该用、什么场景下不该用、与其他技能有什么区别。
举个实际例子。假设你有两个技能：一个叫“获取股票行情”，一个叫“查询股票财务数据”。如果描述都写“查询股票信息”，模型很容易选错。正确的打开方式是这样：
技能名：get_stock_quote 描述：获取指定股票代码的实时或最近收盘行情，包括最新价、涨跌幅、成交量。 适用场景：用户询问“股价多少”“今天涨了还是跌了”“帮我看看某只股票”。 不适用场景：用户询问长期财务指标、净利润、市盈率等，请使用 get_stock_financials。我习惯在描述里明确写“适用场景”和“不适用场景”，这比单纯堆功能说明有效得多。模型在做工具选择时，本质上是在做语义匹配，你给它的判别信息越充分，它选错的概率越低。还有一个细节：描述尽量用动词开头，避免模糊的形容词，让模型一眼看出这个技能“能执行什么动作”。
2.2 输入输出契约：把“自由对话”逼进“结构化车道”
技能的参数设计是重中之重。我见过太多失败的例子：参数定义得太宽泛，模型不知道填什么；或者参数定义得太死板，真实用户表达稍微绕一点，模型就提取失败。
参数设计第一原则是“少而精”。能用三个参数解决的问题，绝不用六个。每个参数都要有清晰的含义、类型、枚举范围、默认值。尤其要注意 enum 的设计，不要光给一个数组，还要给每个枚举值写注释，说明它代表什么业务含义，否则模型只能靠猜。
{ "name": "create_meeting", "description": "创建一场新的会议，并返回会议链接。", "parameters": { "type": "object", "properties": { "title": { "type": "string", "description": "会议标题，例如：产品周会" }, "start_time": { "type": "string", "description": "会议开始时间，ISO 8601 格式，例如：2025-06-10T14:00:00+08:00" }, "duration_minutes": { "type": "integer", "description": "会议时长，单位分钟", "minimum": 5, "maximum": 480, "default": 30 }, "attendees": { "type": "array", "items": { "type": "string" }, "description": "参会人邮箱列表" } }, "required": ["title", "start_time"] } }这里面有两个很容易忽略的点。第一，时间参数必须强制 ISO 8601 格式，否则中文表达“下午三点”会被模型直接塞进参数里，后端一解析就崩。第二，类似 duration 这种有合理范围的参数，一定要写 minimum 和 maximum，给模型一个约束边界。参数校验逻辑尽量在技能入口做掉，不要把事情留给后端接口，毕竟模型填写的参数本身就需要一层防御。
输出契约同样重要。技能返回的数据结构要保持稳定，不要今天返回驼峰，明天返回下划线，后天又嵌套一层 data。我建议所有技能返回统一格式：状态码、消息、业务数据三个字段，业务数据内部再按需组织，这样 Agent 在解析结果时可以走同一套逻辑，不用为每个技能单独写解析分支。
2.3 错误处理与状态反馈：技能不只是“能跑”
技能不是写完就完了，还要考虑失败场景。模型拿到一个执行报错，如果错误信息不友好，它要么重复试探同一个失败动作，要么干脆放弃任务，向用户道歉。这两种结果都不是我们想要的。
我建议每个技能定义三类错误码。第一类是参数错误，说明模型生成的参数不合法，这时应该把期望的格式回传给模型，让它重新生成；第二类是业务错误，比如“余额不足”“权限不够”，这类错误模型无法自动修复，应该直接转成用户可读的提示；第三类是系统错误，比如超时、服务不可用，这时可以做一次重试，不行再降级。
{ "code": "INVALID_PARAMETER", "message": "start_time 必须符合 ISO 8601 格式，示例：2025-06-10T14:00:00+08:00", "retryable": false, "data": null }retryable 这个字段特别有用。模型看到 retryable 为 true 时，可以选择换参数重试；为 false 时，就应该停止调用并如实告知用户。把这个决策逻辑显式化，能避免很多无效的重复调用，节省时间和成本。
3. 从零搭建一个技能库：实操全过程
纸上谈兵讲再多，不如亲手搭一遍。下面我把一套实际可落地的 agent-skills 技能库搭建过程完整记录下来，从目录规划到联调测试，你完全可以照着复现。
3.1 先定目录与命名规范
技能库不是把所有文件堆在一起就行的，目录结构直接影响可维护性。我采用的是“按领域分目录、单技能自包含”的组织方式：
agent-skills/ ├── skills/ │ ├── calendar/ │ │ ├── skill.yaml │ │ ├── create_meeting.py │ │ ├── query_meetings.py │ │ └── cancel_meeting.py │ ├── email/ │ │ ├── skill.yaml │ │ ├── send_email.py │ │ └── search_emails.py │ └── weather/ │ ├── skill.yaml │ └── get_weather.py ├── registry/ │ └── index.yaml ├── tests/ └── examples/每个领域一个目录，每个技能文件独立存在，skill.yaml 负责声明这个技能包的能力范围与注册信息。命名统一用小写加下划线，不用驼峰，文件名也就是技能标识符，方便脚本批量处理。
3.2 技能注册文件怎么写
skill.yaml 是整个技能的“身份证”，它决定了智能体能否正确发现和加载这个技能。我一般会包含这些字段：id、name、version、description、entrypoint、parameters、output_schema、timeout、permissions、error_codes。
id: calendar_create_meeting name: create_meeting version: 1.2.0 description: > 创建一场新的会议，并返回会议链接。 适用场景：用户要求安排会议、约时间、创建日程。 不适用场景：只需要查看已有会议，请使用 calendar_query_meetings。 entrypoint: python3 create_meeting.py timeout: 15 permissions: - calendar:write parameters: type: object properties: title: type: string description: 会议标题 start_time: type: string description: 开始时间，ISO 8601 格式 duration_minutes: type: integer minimum: 5 maximum: 480 default: 30 required: - title - start_time output_schema: type: object properties: code: type: string message: type: string data: type: object error_codes: - INVALID_PARAMETER - CALENDAR_CONFLICT - CALENDAR_SERVICE_ERROR这里有一个经验：version 一定要有，而且每次改接口契约都必须升版本号。技能库里可能有多个 Agent 在挂载同一个技能，升大版本前要做好兼容，否则旧的 Agent 调新技能会直接翻车。
3.3 让技能被智能体“看见”的元数据设计
技能写好了，还得让智能体知道“有哪些技能可用”。这一步我习惯用一个注册索引 registry/index.yaml，集中登记所有技能的加载路径和激活状态：
skills: - id: calendar_create_meeting path: skills/calendar/create_meeting enabled: true weight: 1.0 - id: calendar_query_meetings path: skills/calendar/query_meetings enabled: true weight: 0.8加载器启动时，读取这个索引，把 enabled 为 true 的技能描述全部收集起来，拼装成模型可用的工具列表。weight 字段可以用于控制技能在列表里的排序权重，核心高频技能排前面，模型选中的概率更高。这个设计看似简单，但在技能数量超过 50 个以后，排序和分组直接影响模型的选择准确率，非常值得花时间调优。
3.4 本地联调与回归测试
技能库的测试和普通后端测试不太一样，我一般分三层。第一层是单技能单元测试，直接调用技能入口函数，传合法参数、非法参数、边界参数，验证返回结构和错误码。第二层是模型调用测试，用一个测试用的 Agent，给它一段自然语言指令，看它能否选中正确的技能并生成正确的参数，这一步主要验证描述质量。第三层是回归测试，把过去一个月用户真实问题里涉及该技能的场景收集起来，批量跑一遍，统计成功率有没有下降。
from agent_skills import SkillRegistry registry = SkillRegistry.from_yaml("registry/index.yaml") skill = registry.get("calendar_create_meeting") result = skill.invoke( title="产品周会", start_time="2025-06-10T14:00:00+08:00", duration_minutes=30, ) assert result.code == "OK" assert result.data["meeting_url"].startswith("https://")在跑回归测试的时候，我建议把“模型是否选对技能”和“技能是否执行成功”两个指标分开统计。有时候执行成功率很高，但用户满意率没上去，问题很可能出在模型选错了技能，而不是技能本身有 bug。把这两个指标分离，排查效率会高很多。
4. 常见问题与排查技巧实录
最后聊聊我在实际运营 agent-skills 技能库过程中遇到的高频问题，基本覆盖了从模型到系统、从开发到运维的各个环节，每一条都是真金白银踩出来的。
4.1 模型不调用技能，只想自由发挥
这是最常见的问题。你明明提供了完美的技能，模型偏不调，直接凭训练记忆回答。排查顺序一般是这样：先看技能列表是否真的传给了模型，有些框架默认只传部分工具；再看技能描述里有没有明确的触发信号，比如“当用户询问股价时，必须调用本技能”；最后看是不是技能太多导致模型“选择困难”，这时需要做技能分组或精简列表，让模型面对更少的候选。
还有一个隐蔽的原因：模型对某些技能的名称有先入为主的误解。比如你的技能叫“query_stock_quote”，模型可能觉得“quote”是语录的意思，就是不触发。这时候把技能名改成更直白的 get_stock_price，效果立竿见影。别小看命名，在 agent 场景里，名字就是接口。
4.2 参数传错、类型不匹配
模型生成的参数偶尔完全符合 schema，但值本身是错的。比如用户说要查“上月销售数据”，模型把 start_time 填成上个月 1 号，end_time 填成昨天，但业务上“上月”应该是上月 1 号到上月最后一天。这种问题无法靠 schema 解决，需要在技能内部做业务语义修正。
我的办法是在技能代码里加一层“参数解释器”，把明显不符合业务语义的输入纠正过来。这个解释器不需要很复杂，几个 if 判断就能覆盖大部分场景。注意不要过度纠正，否则会把用户明确的个性化需求改没了，边界要控制好。
4.3 并发与资源竞争问题
技能库一旦被多个 Agent 共用，并发问题就出来了。最典型的是会议室预订场景：两个 Agent 同时收到“预订明天 10 点会议室”的请求，都先查询到空闲会议室，然后同时写入，结果一个成功一个失败。这种竞态必须靠后端服务的原子操作解决，技能层能做的只是失败后重试。
另外一个资源竞争是外部 API 的限流。多个技能共享一个第三方接口时，限流配额很容易被打满。建议每个技能单独配置限流阈值，并在超过阈值时返回 retryable 错误，让 Agent 稍后重试或切换备用渠道。
4.4 技能膨胀后的治理
技能数量上去以后，维护成本会快速上升，甚至出现两个技能功能重叠、模型怎么选都选错的情况。我建议每个季度做一次技能治理：查调用量、查成功率、查重叠度。对半年内零调用的技能，要么删除，要么重新设计；对重叠度高的技能，合并成一个，用参数区分场景。
再分享一个小技巧：在技能描述里加上“deprecated_by”字段，指向替代技能。模型看到这个字段时，就不会再调用旧技能，而是平滑切换到新技能。这样你可以在不通知所有 Agent 的情况下完成技能替换，线上影响面小很多。
id: weather_get_by_city_old name: get_weather_by_city version: 0.9.0 description: > 获取指定城市当前天气。此技能已废弃，请使用 weather_get_forecast。 deprecated_by: weather_get_forecast技能治理这件事，看起来是技术活，其实是产品活。你要站在“模型为什么会困惑”的角度去审视每个技能的存在价值，而不是站在“这个功能当时花了很多精力做得不错”的立场上去保留它。只有舍得删，技能库才能长期保持高可用。
最后再分享一个我个人的体会
做 agent-skills 这一年多，我最大的感受是：技能库的设计水平，决定了智能体能力的上限。模型推理能力再强，你的技能列表定义得含含糊糊、参数契约乱七八糟，最终效果一定拉胯。反过来，只要把每个技能打磨得足够清晰、边界足够明确、错误处理足够完善，哪怕用的是非顶尖模型，也能组合出非常可靠的应用体验。
如果你现在正准备搭自己的技能库，我的建议是别急着多写，先挑三个最高频的业务场景，写出三个设计规范的技能，跑通“注册—加载—调用—观测—迭代”这个闭环。等这套流程顺了，再慢慢扩充。一个经过实战检验的小而美的技能库，远胜过一个看起来功能丰富但处处埋雷的大仓库。
