做 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 的稳定性和可维护性才能真正立起来。