如果说这两年 AI 应用落地最火的一个词那一定是 Agent。但很多人做出来的 Agent本质上是套了一层工具调用的聊天机器人——模型确实会了但让它干点正经活要么不知道该用哪个技能要么一个技能内部逻辑混乱、参数全凭猜。所以当我看到“agent-skills”这个命题时第一反应是这背后想聊的其实是智能体的“能力结构”问题也就是如何把那些零散的工具调用、数据处理、外部接口封装成一套有标准契约、可组合、可复用的技能系统。硬要定义的话agent-skills 就是把智能体可能执行的各类操作拆解成以“技能”为单位的、有明确输入输出边界和能力描述的模块集合。它解决的问题非常具体让 Agent 知道自己会什么、什么时候该用什么、用的时候怎么稳定地跑完。这篇文章不聊大模型怎么选、不聊思维链怎么调只聚焦在技能体系的设计、实现和排障上。适合正在把 Agent 从 Demo 推向真实业务的开发者也适合那些被“Agent 总是选错工具、执行经常半路翻车”折磨的工程师。1. 整体设计思路agent-skills 到底在解决什么问题1.1 一个“能聊天”的框架不等于一个“能干活的”智能体我见过不少团队框架一接让 Agent 去查个数据库、发个邮件演示效果挺好一上生产就原形毕露。原形毕露的典型表现三种第一Agent 明明有对应工具但模型死活选不中每次都在那“抱歉我无法完成”第二工具是调了但参数传得乱七八糟日期格式不对、页码没传、ID 少一位第三工具内部逻辑是写死的换一个业务场景就得改代码。这三种问题的根子都是因为把“技能”和“工具”混为一谈。工具是最小执行单元而技能是一个完整的、可被 Agent 理解和调用的封闭能力块。举个生活化的例子一个技能就像餐厅菜单上的一道菜——菜名是给客人看的description食材清单是后厨备菜的参数烹饪步骤是厨师执行的内部逻辑。如果你只给客人一堆蔬菜和锅铲他根本不知道该怎么点菜这就是只提供工具不提供技能的结果。所以 agent-skills 的设计哲学很简单从模型视角出发把能力描述成它可以“读懂”的规格而不是从工程师视角出发把能力堆砌成一个个函数。所有技能的命名、描述、参数约束都必须假设对面是一个只有上下文、没有源码的模型调用者。1.2 技能库的组成与分层一个可用的技能体系至少包含三个层面。最底下是原子技能也叫叶子技能它们执行单一且不可再拆分的操作比如“发送HTTP请求”“读取本地文件”“执行SQL查询”。原子技能不一定简单但它只有一个职责内部不依赖其他技能。中间层是复合技能它会编排多个原子技能甚至其他复合技能。比如“生成周报”就是一个复合技能它要调“查询数据库”“拉取项目进度”“调用大模型总结”“生成Markdown文件”四个原子技能。复合技能的价值在于把固定的执行路径固化成规则省得每次让模型临场编排既慢又容易乱。最上层是技能注册与调度层包含技能清单manifest、语义索引和路由规则。Agent 收到用户请求后先通过语义匹配从技能清单里选出候选技能再根据候选技能的输入约束生成参数并调用。这一层还可以加路由策略比如优先级规则、权限控制、负载均衡是技能体系里最容易扩展也最容易被忽略的模块。我见过很多团队把原子技能写得很好但缺了中间层导致 Agent 每次都要排列组合十几个原子技能去完成一个复杂目标推理成本翻倍还容易断链。所以我的建议是技能粒度可以细但对外暴露的技能粒度尽量粗。模型需要的不是“99%的概率能串对流程”而是“100%用一个技能干完一件事”。1.3 和“插件”“工具”的关系应该怎么划清如果团队之前用的是 Plugin 或 Function Calling新增技能体系时最纠结的通常是那我要不要推翻重来我的经验是没必要推倒重建而是把“插件”和“技能”看成两个正交维度的东西。插件是载体和分发维度它解决的是“代码以什么形态部署、如何被加载”技能是能力和语义维度它解决的是“能力用什么接口暴露、如何被理解”。一个技能可以部署在一个插件里一个插件也可以承载多个技能。打个比方插件是抽屉技能是里面的工具——你换了抽屉工具还是那些工具你把工具重新分类摆放也没必要换抽屉。因此在落地 agent-skills 时我建议不要纠结命名直接把现有 Function 加一层技能描述规范就可以了给每个 Function 配上标准化的 name、description、parameters schema、执行策略和错误处理策略并在注册中心登记成技能。这样就完成了从“函数直觉”到“技能思维”的切换代码改动量却不大。2. 核心细节解析技能的契约、命名与边界2.1 description 是 GPS不是说明书技能设计里最反直觉的一件事是description 写得越详细模型反而越容易用错。原因很简单大模型做技能选择时依赖的是语义匹配如果你的 description 是把内部实现写了一遍模型会被细节带跑抓不住这个技能的核心用途。我自己的经验是描述分三段写。第一段一句话说明技能是干什么的动词开头包含核心对象和意图比如“查询用户在指定时间范围内的订单金额总和”第二段写清楚适用条件和典型场景比如“当用户问到某个时间段内共消费多少时使用”第三段写边界和禁忌比如“仅用于已登录用户的订单数据不支持跨用户数据合并”。这还有个额外好处description 写得清楚Agent 就不会“过度思考”要不要调用。模型在最上层做意图识别时看到一个精准的技能描述匹配速度快得惊人反而是那种啰嗦的描述会让它在三四个候选技能之间反复纠结最后都调不对。2.2 参数设计宁可收敛不可发散参数 Schema 是技能契约的核心也是最容易偷懒的地方。很多团队的技能参数只有一个大字符串让模型“自由发挥”执行阶段再解析。这种做法短期能用长期必然出问题模型输出的格式稍微漂移解析就失败而解析失败的错误信息模型也看不懂就陷入死循环。我给一个收敛型参数设计的三个原则。第一参数要有语义化的 JSON Schema。每个字段都要有description说明取值范围、单位、格式。比如时间字段要写“ISO8601格式默认当前时间”而不是笼统写“一个时间”。模型对字段描述的理解直接决定了它填的参数准不准这里的投入产出比非常高。第二参数要有合理的默认值和容错。能不给模型选择权的就不给。比如“是否发送通知”这种布尔值默认 false除非用户明确要求否则模型不会主动去把它改成 true。减少参数的“自由度”就是在减少模型的“犯错率”。第三输出结构要稳定。技能执行完的返回值最好统一包装成{success, data, error}三字段结构不要有时返回字符串有时返回对象。因为 Agent 后续的推理依赖返回值结构结构不稳定它就没法稳定决策下一步。这跟写 API 契约的道理一样只不过对面的调用方是一个概率模型对不稳定性的容忍度更低。2.3 运行边界幂等、超时、并发技能上了生产环境之后真正决定生死的不是功能实现而是边界控制。这里我强调三个关键词幂等、超时、并发控制。幂等性是最容易被忽略的。一个“创建工单”技能如果 Agent 因为网络抖动重试了三次就创建了仨工单用户不炸才怪。所以技能实现里必须支持幂等键idempotency key调用方传入一个唯一请求ID技能内部先去查一下这个 ID 有没有处理过处理过直接返回上一次的结果。这个设计在支付、消息发送、数据写入类技能里尤其重要。超时控制要细分到网络调用和整体运行两个层面。整体运行超时设在 Agent 单步执行的上限之内通常 30~60 秒比较合适网络调用超时则要更短比如 5 秒避免技能卡在某个外部接口上“装死”。我踩过一个坑某个技能内循环跑了 3 分钟才超时外面 Agent 已经放弃了但技能还在占着资源最后并发一高直接拖垮服务。所以超时的设置原则是外层时间要短于用户可接受的等待内层时间要短于外层时间。并发控制则是为了防止技能被多路同时调起导致资源竞争。比如一个技能依赖某个受限的第三方 API你至少要给它加一个简单的信号量比如同一技能最多同时跑 3 个实例超出排队。这看起来是基本功但确实见过不少团队把 Agent 并发做上去了技能层却没有保护最终把上游接口打挂的案例。3. 实操过程与核心环节实现3.1 从零实现一个“竞品价格监控”技能说再多理论不如直接复现一个完整技能。我这里以实现一个“竞品价格监控”技能为例演示从定义、编码到注册的全流程。先做需求拆解。这个技能的输入是竞品商品 URL 列表、目标价格阈值输出是哪些商品价格低于阈值差价多少。整个执行逻辑分四步抓取页面、解析价格、对比阈值、汇总结果。设计技能描述和参数 Schema{ name: track_competitor_prices, description: 监控指定竞品商品的价格当价格低于或等于目标阈值时返回提醒。适用于电商比价、价格预警场景。当用户提供竞品商品链接和期望价格时使用。, parameters: { type: object, properties: { products: { type: array, items: { type: object, properties: { url: { type: string, description: 竞品商品页面URL }, name: { type: string, description: 商品名称用于展示 }, threshold: { type: number, description: 目标价格阈值单位元 } }, required: [url] } }, notify: { type: boolean, description: 是否在有匹配结果时发送通知默认false, default: false } }, required: [products] } }接下来是核心执行逻辑用 Python 写一个简化但完整的版本。注意这里我用的是可插拔的抓取和解析策略方便适配不同站点结构import asyncio import aiohttp import json class CompetitorPriceTracker: def __init__(self, parser_adaptersNone): # parser_adapters: 每个站点对应一个解析函数 self.parser_adapters parser_adapters or {} async def _fetch_price(self, url: str) - float: async with aiohttp.ClientSession() as session: async with session.get(url, timeout5) as resp: html await resp.text() # 按站点域名选择解析器这里省略正则与解析细节 for domain, adapter in self.parser_adapters.items(): if domain in url: return adapter(html) raise ValueError(funsupported site: {url}) async def execute(self, products: list[dict], notify: bool False) - dict: results [] for product in products: try: price await self._fetch_price(product[url]) threshold product.get(threshold, 0) matched price threshold results.append({ name: product.get(name, product[url]), url: product[url], current_price: price, threshold: threshold, matched: matched, diff: round(threshold - price, 2) if matched else None }) except Exception as e: results.append({ name: product.get(name, product[url]), url: product[url], error: str(e), matched: False }) return {success: True, data: results}这个示例里有一个非常关键的取舍我把“价格解析”做成了可插拔的而不是写死。原因是电商站点的页面结构经常变一旦 HTML 结构调整改技能的频率可能比改业务代码还高。通过适配器模式可以做到站点结构变化时只改对应解析函数不影响技能本身的执行流。把技能注册进 Agent 之前还必须先跑一轮离线测试。我会构造三个用例正常 URL、一个解析失败的不支持站点、一个超时的 URL确认技能输出结构符合预期。这一步看似费时间却能避免上线后被模型“用奇怪的方式”反复调用同一个错误逻辑。3.2 复合技能把三个原子技能编排成数据分析流水线复合技能才真正体现 agent-skills 的架构优势。我再用一个“电商价格周报生成器”做例子它内部编排三个技能track_competitor_prices、aggregate_price_changes、generate_markdown_report。设计复合技能时需要额外定义一个编排流程我用一个简单的顺序编排器来表示class PipelineSkill: def __init__(self, steps: list): self.steps steps # 每个 step 是 (技能名, 参数映射函数) async def execute(self, state: dict) - dict: for skill_name, map_fn in self.steps: # 从 state 中提取该技能所需的参数 step_input map_fn(state) # 调用对应的技能执行器 step_output await registry.call(skill_name, step_input) # 把输出写回 state供后续步骤使用 state[skill_name] step_output return {success: True, data: state}在定义复合技能的参数时我额外加了一个report_meta字段用于指定周报标题、数据范围和输出路径这些参数会映射到下游的generate_markdown_report技能。这样设计的好处是对 Agent 来说它只需要描述“生成一份上周的竞品价格周报”并给出少量关键参数剩下的编排细节全在复合技能内部完成完全不用模型操心。复合技能最容易出的问题是“技能之间参数错位”。比如track_competitor_prices返回的字段叫current_price而aggregate_price_changes期望的字段叫price。这种名字不一致会在编排链路上静默产生错误数据。我的解决办法是定义统一的内部数据模型并且每个技能的输入输出都对齐这个模型而不是各写各的。这相当于给技能编排层加了一个“接口契约”一劳永逸。3.3 接入 Agent 框架函数调用与 ReAct 的接入差异技能系统无论多么完整最终都要接到 Agent 执行框架上。目前主流接入方式有两种函数调用Function Calling和 ReAct 风格的工具调循环。两者对技能定义的要求略有不同。如果走函数调用路线技能描述和参数 Schema 基本可以原样映射为框架里的 function spec。你甚至可以把每个技能的description直接拼进 system prompt 或作为工具的元描述。需要注意的一点是有些框架对工具数量和 token 长度有上限如果技能库超过几十个就得加一层技能检索retrieval先用语义检索筛出 top 5 技能再注入到调用列表中。这一步在技能体系设计时就要考虑到否则后期技能一多Agent 会因为上下文过长或注意力分散而频繁选错。如果走 ReAct 路线技能描述会直接暴露在模型可见的文本上下文中每多一个技能描述都在挤占模型的注意力窗口。这种场景下description 的前三句话就尤其重要因为它会被优先读取。我的习惯是把最关键的一句话放在描述开头后面的补充信息用“仅当...才继续阅读”这种措辞来压缩无意识消耗。实测下来这个细节能让工具选择准确率明显改善尤其是技能数量超过 15 个以后。接入阶段还需要注意同步机制。比如技能注册中心更新后要确保所有运行中的 Agent 实例都能拿到最新技能列表不能出现“技能已经下线但 Agent 还在尝试调用”的情况。我做过一个简单的做法技能注册中心维护版本号Agent 每次执行前检查版本号不一致就重新拉取注册表。成本低但能避免大量诡异故障。4. 常见问题与排查技巧实录4.1 八类高频故障速查表技能系统上了生产之后故障模式比普通后端服务更刁钻因为多了一个“概率模型调用者”。我整理了八类最高频的问题和对应解法全是实际踩过坑的。症状可能原因排查方法解决方案Agent 一直不调用某个技能description 语义太窄或与用户意图表达差异大把用户实际 query 和技能描述放一起语义检索看相似度改写 description加入场景化表达和同义词调用频率极高但执行成功率低description 没有写清使用边界看失败日志中模型传入的参数是否符合预期在 description 中加“不适用场景”并收紧参数校验参数总是缺字段或格式错误JSON Schema 字段描述模糊或默认值缺失统计失败调用的参数结构找出高频错误字段给每个字段加明确描述能设默认值的全设默认值技能执行超时拖垮 Agent技能内部网络调用没有细分超时用链路追踪查技能内耗时分布内层网络调用单独设 3~5 秒超时整体设 30 秒上限同一任务重复执行产生重复数据技能缺少幂等键处理检查多次执行记录的 requestId 是否一致引入幂等键和去重表相同请求ID直接返回旧结果多个技能结果互相覆盖复合技能编排层参数错位或共享状态被覆盖逐步打印每个步骤的输入输出对比字段名统一内部数据模型定义数据契约上线新技能后整体效果下降技能数量过多导致模型选择注意力分散查看技能列表被完整注入后的调用准确率增加技能检索层每次只注入 top N 个候选技能技能正常但 Agent 声称执行失败返回结构不统一模型无法解析输出检查返回值是否始终为{success, data, error}结构统一包装返回值并在技能测试中覆盖异常分支第一行到第四行是“选错技能”和“参数乱传”的高频区几乎每个 Agent 项目都会遇到。第五行和第六行则是从 Demo 到生产的门槛尤其在涉及写入型操作的场景里幂等性缺失是事故高发点。第七行出现时往往已经具备一定的技能规模属于预判型问题提前做检索机制更好。4.2 两个独家排查技巧在故障排查里我总结出两个非常有用但文档里很少提到的技巧。第一个技巧叫“技能调用日志的语义化记录”。普通日志只会记录技能名、参数、返回值和时间但排查 Agent 问题的时候更需要知道“模型为什么选了它”。所以我在技能执行入口加了两条额外日志一是模型当时的计划文本或推理片段二是候选技能列表及其得分。这样一旦出错可以反推是语义匹配失败、参数生成错误还是执行逻辑缺陷。没有这个记录排查就像盲人摸象只能靠猜。第二个技巧是“技能集的最小化回归集”。每次技能库上线新版本不要只测新增技能而是维护一个包含 20~30 条典型用户问法的回归集自动跑一遍技能选择的准确率和执行的成功率。很多问题是叠加出来的新技能描述风格和旧技能不一致导致模型在新旧之间摇摆新技能参数约束过松抢走了本该属于其他技能的调用。没有回归集这类回归问题很难被发现等用户投诉了才知道。这两个技巧的投入产出比极高。它们不需要复杂的基础设施只需要在现有日志系统和测试流程里多埋几个点但确实能把 Agent 应用的“玄学感”压到最低。回到技能设计本身我个人在实盘里的体会是agent-skills 的难点从来不在单个技能怎么实现而在整体体系怎么保持“模型友好”。你写的每一个 description、每一个参数约束本质上都是在跟一个概率模型对话。你越用契约思维去规范它它就回馈给你越稳定的执行结果。如果你正准备搭建自己的技能库我的建议是先把文档规范写好再写代码——这跟传统工程的习惯正相反但在 Agent 领域文档就是代码的“另一半”。
