做 AI Agent 做得越久，我越发现一个现象：很多团队拿着目前最强的一批大模型，搭出来的 Agent 却只比聊天机器人多一口气——能调个 API、能搜个网页，但一换任务就抓瞎。问题往往不在模型，而在技能层。agent-skills 这个词，看起来像是一个开源项目名，实际上代表了 Agent 工程里最关键的一层设计：把“模型会说话”转成“模型会干活”的那套技能定义、装载、调用、编排和管理机制。这篇文章我会把 agent-skills 从概念到落地拆开讲一遍：它到底解决什么问题、技能怎么定义、执行链路怎么搭、常见坑怎么排。适合正在做 Agent 落地、或者被“提示词越来越长但效果越来越不稳”折磨的开发者参考。
很多人把 Agent 的能力直接写在系统提示词里，比如“你可以调用搜索工具、可以调用计算器”，然后给几个 JSON 示例就算完事。前期确实能跑通，但等项目规模上来，这种写法会变得非常痛苦。agent-skills 的核心思路，是把模型能力和真实世界任务之间的那层胶水，做成独立于提示词之外、可管理、可复用、可观测的技能系统。这套东西不玄学，就是一套工程规范加运行时设计。下面我会从设计思路、定义方法、生命周期、实现细节、问题排查几个维度，把我在实际项目里沉淀下来的经验完整写出来。
1. 先聊清楚：agent-skills 到底解决什么问题
1.1 从“会聊天”到“会干活”的技能层
大模型本身擅长的是文本生成，不是执行任务。你让它“帮我查一下这个订单的物流信息”，它不能真的去查询；你让它“把这批数据按规则清洗一遍”，它也不能真的处理。Agent 和 Chatbot 的边界就在这里：Agent 需要外部工具、接口、脚本、数据库查询等真实操作来完成任务，而模型在其中扮演的是“大脑”和“调度器”，不是“手脚”。
agent-skills 就是给大模型配置的这一套“手脚”。一个技能通常包含以下要素：一个触发这个技能的意图描述、一段告诉模型何时使用该技能的指令、一个结构化的参数接口、一段实际执行的代码或工具调用，以及一个返回结果给模型解析的规范。和直接写“你可以使用以下工具”相比，技能层的价值在于它能独立演进、独立测试、独立复用。同一个“查天气”技能，既可以用在客服 Agent，也可以用在旅行规划 Agent，不需要重新写提示词。
1.2 为什么不能把所有逻辑塞进 Prompt
我在很多项目里见过一种失控：系统提示词越写越长，工具说明越来越详细，上下文里塞了几十个 JSON Schema，模型开始“忘”掉部分工具的存在。这不是模型不行，而是信息熵太高。提示词里的工具描述和真实执行逻辑之间如果没有明确边界，模型很难稳定地做选择。
把技能从提示词中剥离，改由运行时动态装载，好处有三层。第一层是上下文精简，只需要把当前任务相关的几个技能描述给模型，而不是一次性给几百个；第二层是执行可靠，技能对应的是真实可跑的函数或脚本，模型只负责填参数，不需要自己“编造”代码；第三层是治理清晰，每个技能有明确的负责人、版本、测试用例和调用统计，这是工程化 Agent 的基本门槛。agent-skills 不是某种特定框架的专利，它是一种设计范式。理解了这层，后面所有实现细节都会顺理成章。
2. 技能拆解与定义：把 Agent 的能力变成可管理的单元
2.1 一个技能的最小组成结构
先给一个我在项目里一直在用的最小结构定义。它不完全等同于某个框架的写法，但适用于大多数 agent-skills 实现。
一个技能至少要包含四样东西：
- 技能标识符：全局唯一的名称，如
order_query、invoice_ocr_handler，命名尽量用下划线小写风格，方便代码引用和日志过滤。 - 技能描述：一句话说清“这个技能做什么，适合什么场景”，这是给模型看的主要依据。描述写得越准确，模型选错技能的概率越低。
- 参数规范：用结构化 JSON Schema 描述模型需要填哪些参数，每个参数的类型、必填性、取值范围。
- 执行处理器：一段真实执行的逻辑，可以是本地函数、HTTP 请求、Shell 脚本、数据库查询等。
在实际项目中，我会额外增加两个字段：技能权限级别和技能版本号。权限级别用来约束什么场景下允许执行危险操作，比如删除、写入、外呼；版本号方便技能在运行中热替换，也方便对比新旧版本的调用效果差异。
2.2 定义几个核心技能模块的实操示例
用一个实际例子来看定义过程。假设我们要给 Agent 加一个“订单查询”技能，第一步不是写代码，而是写技能说明书。
技能说明书大概长这样：
skill_name: order_query description: >- 当用户询问订单状态、物流进度或发货时间时使用。 支持通过订单号查询，也支持通过用户手机号查询最近订单。 parameters: order_id: type: string description: 订单编号，例如 SO202411150001 required: false phone: type: string description: 下单手机号后四位 required: false handler: scripts/order_query.py timeout_ms: 3000这段定义里有几个细节值得注意。描述里我特意写了“订单状态、物流进度或发货时间”这样的自然语言触发场景，而不是只写“订单查询”，因为模型是靠语义匹配来决定是否调用技能的，描述越贴近用户的真实提问方式，命中率越高。两个参数都不是必填，但这并不意味着模型可以随意省略——我在处理逻辑里会要求order_id和phone至少给一个，否则返回参数校验错误。这种冗余设计给了模型纠错空间，比“要求必填”更稳健。
再比如“文件列表获取”技能，定义时我会在参数里加入path和recursive，描述里写清楚“仅限工作目录下，不可访问系统关键路径”，并在执行处理器里做路径白名单校验。定义一个技能不只是一段声明，还包含了安全边界。这个边界放哪都行，但必须在技能层完成至少一次校验，不能指望模型自觉。
2.3 技能间依赖与编排策略
有些任务不是单技能能完成的。比如“帮我查一下最近一个订单，如果显示已签收就发一个回访短信”，这里面涉及订单查询技能和短信发送技能。agent-skills 需要处理两个问题：技能之间需要顺序依赖，以及一个技能的输出如何变成下一个技能的输入。
我的建议是不要做技能内部互相调用的复杂图结构，而是引入一个独立的编排层。Agent 首先收到用户请求，模型根据结果选择多个技能并按顺序执行。上一技能返回的 JSON 会回填到下一技能的参数中，这个回填过程可以交给模型，也可以通过代码做字段映射。我更喜欢把简单的字段映射用代码写死，比如前一个技能返回的order_id直接传给下一个技能的同名参数；只有映射关系不确定时，才让模型参与决策。这样能减少模型不稳定性带来的连锁错误。
在技术选型上，不建议自己实现流程编排引擎。哪怕只有三五个技能，用条件判断加循环实现编排，代码也会变得难以维护。可以选用成熟的工作流框架，或者至少把编排过程抽成独立于技能执行之外的一层。心里要清楚：技能本身是原子能力，编排是策略，两者分开才能各自演进。
3. 按生命周期组织 skills：发现、注册、执行、退役
3.1 技能的发现与注册流程
很多人一开始只写技能函数，不写注册表。等技能超过十个以后，问题就来了：你很难知道系统里到底有哪些技能，哪些还用着，哪些已经废弃了。agent-skills 的生命周期管理，第一步是建立一份技能注册表，可以理解成一个数据库表或者一个目录约定。
我习惯用一个skills/目录，每个技能一个子目录，里面放SKILL.md用于说明文档、schema.json用于参数声明、handler.py用于执行逻辑。系统启动时扫描这个目录，动态加载所有技能，自动构建技能列表。这个做法带来的好处是加新技能不需要改核心代码，只要新增目录并符合约定，运行时会自动发现。注册信息至少包括技能名、版本、描述、参数 schema、执行入口、作者。
注册时还需要做一件事：把技能列表压缩成给模型看的“技能索引”。我实测下来，当技能数量超过 15 个时，把所有描述全部塞给模型会产生显著的决策质量下降。更合理的做法是两级检索：第一级根据用户问题先用轻量 embedding 或者是关键词匹配召回候选技能（5 个以内），第二级把候选技能的完整描述和参数 schema 拼接进上下文供模型精确选择。这样既解决了上下文过长问题，又把技能发现机制从全量遍历变成了索引检索，效率和质量都能稳住。
3.2 执行引擎与上下文路由
技能注册之后，执行层需要回答一个问题：这一次模型决定调用技能，平台如何把请求路由到正确的处理器并执行？
我实现的执行引擎核心代码逻辑可以归纳成四步：
- 解析模型返回的工具调用结构，比如
{"skill": "order_query", "arguments": {"order_id": "SO202411150001"}}。 - 从注册表中查找对应的处理器入口。
- 校验参数，刷新过期字段，补充默认值，做一次安全过滤。
- 执行处理器，把返回结果结构化为统一格式，回传给模型作为下一轮推理的新增观察结果。
这里有一个被很多人忽略的细节：上下文路由。执行完成后的输出，不只是给用户看的，更是给模型下一轮推理看的。所以返回结果必须结构化、精炼化。比如订单查询的结果，直接返回一行概要文本加上一个 JSON 对象，而不是把数据库原始记录全部塞回去。模型观察空间越干净，下一步决策越准。
建议在执行引擎里统一记录每个技能的耗时、Token 消耗、成功失败状态。这些数据是后面做技能评估和优化的重要基础。没有观测，就没有迭代。
3.3 技能退役与版本管理
技能不是写出来就能永久运行的。业务会变、接口会变、模型能力也在变。有些技能可能三个月没有一次调用，有些技能可能因为上游 API 升级而报错。如果不做退役机制，会有大量“僵尸技能”占据动态装载空间，甚至在召回阶段造成噪声。
我建议每个技能打上版本号，并在注册表中记录创建日期、最近调用日期和调用次数。定期跑一次统计：如果某个技能连续 30 天调用次数为零，就标记为“Draft”；再等 30 天还是零，就标记为“Deprecated”，并从默认召回索引中剔除。注意不要立刻删除代码，标注 deprecated 后仍在注册表中保留，只是不再进入模型可见列表，这样万一业务需要恢复还有回退余地。
版本管理上，我采取“每个技能独立版本，整体快照统一发布”的策略。每当一组变更上线，就产生一个 Agent 技能快照版本号，比如skillset-20250112-1。这样如果新版本行为异常，可以整体回滚到上一个快照，而不需要逐个技能回滚。这个思路和微服务里的版本发布很像，本质是把不可预测的模型链路变成可回滚的工程系统。
4. 实操：让我踩过坑的 agent-skills 实现细节
4.1 技能定义的数据结构选型
技能定义用什么结构，直接决定了后面解析、校验、装载的复杂度。我一开始用纯 Python 字典手写 schema，后面发现只要技能稍微复杂一点，手写很容易出现字段类型不一致、嵌套层级漏写等情况。后来切换到 JSON Schema 标准，很多语言都有现成的校验库，不需要自己造轮子。
以参数定义为例，我强烈建议对每个字段设置description，并且用约束条件限制枚举值、字符串长度、数字范围。模型不是万能的，不在 schema 里限制的东西它就真的可能乱填。比如一个“客户等级”字段，如果 schema 里写了enum: ["A", "B", "C"]，模型几乎不会填出“普通用户”这种无效值；如果不写，10 次里面有 3 次会填出 schema 之外的内容。JSON Schema 的additionalProperties: false也要打开，防止模型添加预定义之外的参数。
还有一个容易踩的坑：不要用 Python 类直接用__dict__当作技能定义。类的继承关系会让字段来源不清晰，序列化也容易带上无关属性。用标准 JSON 文件或 YAML 文件作为技能定义的唯一事实来源，然后加载成 Python 对象，清晰度和可维护性都会好很多。
4.2 模型与技能之间的调用衔接
这个模块是 agent-skills 实现中最容易出问题的地方，因为模型返回的“函数调用”并不总是符合预期。即使是用函数调用模式的大模型，依然可能出现以下异常情况：技能名不在注册表中、参数为 null、参数类型错误、多了大段无意义的描述、甚至出现两次调用嵌套输出。
针对这些异常，我的处理策略是“宽容校验、明确反馈”。宽容校验不是指放宽参数标准，而是对可以被修复的小问题自动修复，比如把数字参数“4.0”转成 4，把字符串参数首尾空格清掉，把 timezone 变成 standard 字符串。对于无法修复的问题，不是简单报错，而是返回一条清晰的观察信息给模型：“调用 order_query 失败，参数 phone 缺少 4 位数字，请补全后重试。”这样模型在下一步就可以自行纠正，而不是整个链路线性崩断。
还有一点很关键：技能调用的返回必须区分“执行成功但结果为空”和“执行失败”。很多团队不区分，导致模型把空结果误判为异常重试，或者把失败误判为成功。我在结构化返回中会固定加一个status字段生成success、error、empty三种状态，并且把语义化的原因放在summary字段里。这样模型看状态字段就能决定下一步做什么，比让它从一堆原始文本里猜要可靠得多。
4.3 错误处理与重试策略
Agent 执行过程中，技能报错几乎是必然的。网络超时、依赖服务降级、参数边界问题都会造成失败。如果不做重试策略，一次用户请求会直接失败；如果盲目重试，又可能造成重复扣费、重复通知等灾难性问题。
我的经验是给每个技能定义两类超时重试策略。第一类是幂等技能，例如查询、日志、计数，允许自动重试两次，每次间隔 200ms 并采用递增退避（比如 200ms、800ms）。第二类是非幂等技能，例如发短信、创建订单、扣款，禁止自动重试，错误后直接返回失败状态，由编排层决定是让用户二次确认还是回退到人工。实际操作中，我还会在技能定义里加一个标记，例如idempotent: true/false，执行引擎根据这个标记来决定错误处理分支。
重试之外，还需要设置整体链路超时。单技能超时往往不够，因为编排层可能连续执行多个技能，总耗时会失控。我给整个 Agent 任务设了一个默认总超时 30 秒，一旦超过立即终止，并向用户返回“执行超时，请稍后再试”。总比让用户对着一个转圈卡死的页面强得多。
5. 常见问题与排查实录
5.1 Agent 就是不调用你的技能怎么办
这是最经典的问题：技能定义没问题、执行也没问题，但模型就是绕过去，直接凭记忆回答。排查时不要先怀疑模型，先排查召回层。你有没有把技能给到模型？给的是完整描述还是只有一句话索引？如果技能描述和用户问题之间语义距离太大，模型可能根本意识不到这个技能存在。
我遇到过的一个具体案例是：技能描述只写了“查询订单”，用户问“我这个快递到哪了”，模型认为“快递”和“订单”不像是一回事，就没有调用。解决办法是把描述改得更口语化、更场景化：“查询订单、快递、物流、发货相关信息，包括订单状态、配送进度、快递单号跟踪”。改完之后调用次数立刻上去了。
另一个原因是上下文里的技能说明太多，模型被其他相似技能干扰。比如有两个技能描述都包含“查询”二字，模型就可能选错。解决方式是给每个技能加上差异化的触发词，并且在召回阶段做到互斥归类。如果你发现某个技能总是被覆盖，把它放到更高优先级的召回分组里，或者把相似技能先做一次合并。
5.2 技能参数填错、幻觉参数怎么治
模型对参数的理解不一定准确。让它填用户地址，它可能填一个缩写；让它填日期，它可能填“今天”；让它填金额，它可能填“46元”而不是数字 46。这种问题不能靠期望模型自动改正来解决，得在 schema 约束上做文章。
首先，每个字段都要写明格式和示例，尤其是日期、时间、金额、代码这类对类型敏感的参数。其次，强烈建议在参数描述里加上“不要包含单位”“填写 XX 格式”等限制性提示。最后是入口侧校验：在 schema 层严格限制type和pattern，例如金额字段type: number，日期字段type: string且pattern: ^\d{4}-\d{2}-\d{2}$。如果模型填了“2025年1月1日”，正则校验就会弹回，模型会看到错误提示后重新修正。
还有一个比较隐蔽的幻觉参数问题：模型会补全你没定义的字段，比如user_id填上它猜的0或-1。上面提到的additionalProperties: false在这里非常重要。关闭额外字段之后，模型乱填的字段会被直接丢弃，而不是进入执行层造成隐患。
5.3 多技能并发时的资源竞争
当多个任务同时执行，或者一个任务里并行调用多个技能时，资源竞争问题会迅速暴露。最常见的是数据库连接数被打满，或者 API 限流触发。技能层需要做两件配套的事：信号量控制和缓存。
我给每个技能配置最大并发数，比如数据库查询类技能最大同时执行 10 个，超过的直接排队或快速失败。这个配置写在技能描述文件里，执行引擎统一调度。缓存也很重要，对于查询类技能，同一个参数在 60 秒内的结果直接复用，不再请求下游服务。很多线上 Agent 瘫痪不是因为模型能力不行，而是技能并发控制没做，直接把下游接口打挂了。
还有一类资源竞争和 Token 有关。多技能并行时，模型要处理的观察文本量会大幅增加。如果每个技能都返回完整的大段文本，最终上下文会被冲爆。解决办法是所有技能返回仍然遵循“摘要优先”的原则：默认返回最多 500 字的结构化摘要，需要更多细节时再由模型主动调“扩展详情”技能。这种薄返回设计在并发场景下非常实用。
6. 从项目里沉淀出来的建议
6.1 先做薄技能层，再做厚业务
新手最容易犯的错误是第一天就想做一个万能 Agent，把所有业务功能塞进一个 super skill。这种设计会让技能层变成一个巨大的条件分支，既不便于测试，也不便于模型选择。我更推荐反着来：先做视线可及的薄技能层，一个技能只干一件事，哪怕它很简单。例如“获取当前时间”“查询天气”这种看起来没有技术含量的技能，也值得单独定义。
薄技能层的好处是每次调用的行为可预期，模型选错的范围更小。等每个技能都稳定后，再通过编排把多个原子技能组合成厚的业务流程。这个顺序不要反过来。我自己做过一个教训很深的项目：一开始就把“订单全流程处理”写成一个技能，内部逻辑超过了 800 行，模型经常胡乱选择，根本无法定位问题。后来拆成查询、退款、改派、通知四个薄技能后，稳定率提升非常明显。
6.2 给技能加可观测性
技能不可观测，就等于黑盒。每次调用谁选的、选后执行多久、花了多少 Token、成功还是失败，这些数据如果不清不楚，后续做任何优化都是拍脑袋。
我在技能执行引擎里强制埋了三个点：开始、结束、异常。开始记录调用时间、入参、调用链来源；结束记录返回摘要、耗时、token 消耗；异常记录异常类型、堆栈信息、是否重试成功。有了这些数据之后，我可以直接画出技能的调用热度表、失败率排名和平均耗时，一眼就能找到瓶颈。
更进阶的做法是对每次调用打上一个request_id，从用户请求、到技能调用、到编排过程，全链路都挂上这个 ID。这样当业务方来投诉某个 Agent “答非所问” 时，我可以用 request_id 拉出完整链路，看看问题到底出在技能选择还是参数生成还是执行错误。可观测性不是一个加分项，是 Agent 工程从 demo 走向生产线的必经之路。
6.3 技能评估用真实任务流
很多人评估 Agent 技能时，喜欢单测一个个技能，测试文本都写得非常简单，比如直接问“查订单号 SO001”。这种测试过完一遍，上了线还是一堆问题。因为真实用户不会按你的测试文本来提问，他们的说法有歧义、有指代、有缺失信息。
我现在的评估方式是维护一份“真实任务流”测试集，每条样本都来自真实用户脱敏数据，并且按难度分成三档。第一档是直接指令，用户明确说了动作和参数；第二档是隐含意图，用户只说要什么结果，需要模型自己推理选择技能；第三档是干扰场景，用户的问题里包含无关信息，或者知识和所需信息不完全匹配。
每次技能变更后，我都会跑一遍这个任务流评估集，对比变更前后技能选择准确率、参数填对率、任务完成率和平均耗时。如果某次变更导致第一档任务完成率下降，那说明基础链路出了问题，需要先修再上线。这套评估的维护成本确实不低，但它是 agent-skills 长期可靠运行的唯一保险。
最后再分享一个我个人的习惯：每次给 Agent 加新技能时，我会先写技能说明，再写 handler，最后写测试用例，顺序不能反。说明写好代表想清楚了触发场景和参数边界；handler 写好代表能落地执行；测试用例则锁定验收标准。这个习惯帮我避开了大量“代码跑得通但模型根本不调用”的返工。agent-skills 不是某个库的名字，它是一种工程纪律，把这条纪律贯彻到团队和流程里，Agent 的稳定性和可维护性才能真正立起来。
