做 Agent 这两年我最大的一个感受是真正拉开项目差距的往往不是模型选得有多强而是你给 Agent 配了一身什么样的“技能”。这里的 agent-skills 不是指模型本身会什么而是指你通过工具调用、指令编排、上下文管理让大模型真的能上手干活的那一套能力封装。有人叫它技能库有人叫它工具集本质上是一件事把“模型会说话”变成“模型会做事”。这篇文章会把我从零搭建 agent-skills 的整套思考、结构定义、落地步骤和踩坑记录全部摊开聊。适合正在做 AI Agent 应用、想把手头零散工具升级成结构化技能体系的同学。看完你至少能回答这几个问题技能和工具到底什么区别、技能拆多细才合适、一个生产可用的技能要写哪些字段、以及 Agent 不按你预期调用技能时应该怎么排查。1. 整体设计思路为什么你的 Agent 需要一套“技能体系”1.1 工具、技能、任务先把概念掰清楚很多团队一上来就干代码结果第一步就栽在概念上。工具、技能、任务这三个词看着差不多设计上完全是三个层次。工具是最小的可调用单元比如“打开浏览器”“读取某个文件”“发一条 HTTP 请求”。任务则是用户的最终目标比如“帮我做一份竞品调研报告”。技能是夹在两者之间的能力封装组合了“触发条件 执行流程 若干工具调用 结果规整”这几样东西。我习惯用一个比喻工具是螺丝刀、电钻这些裸工具任务是“装好一个书架”技能则是一套标准作业流程——知道先量尺寸、再打孔、再固定层板。Agent 如果只有裸工具它每次都得现场想流程结果时好时坏有了技能它就像请了个熟手师傅稳定性和效率一下就上来了。这个区分不是文字游戏。你如果把“任务”当“技能”封装技能会变得又大又笨几乎没法复用你如果把“工具”当“技能”封装Agent 就要在每一轮对话里自己编排几十个步骤上下文很快就会爆掉。1.2 拆成技能到底换来了什么把能力封装成技能不是多此一举。我在实际项目中体会到四个直接的收益。第一是复用。多个 Agent 都要走“搜索网页 抓取正文 生成摘要”这条链路封装成一个技能之后谁需要谁直接声明引用不用重复写 prompt也不用重复调接口。第二是稳定性。流程被固化下来成功率就可测、可调。这个月模型不调这个技能了上个月调用率是 92% 还是 72%一眼就能看出来不用靠感觉。第三是低成本迭代。底层接口变化、模型升级、prompt 调整都只改技能内部技能对外的接口保持不变调用方完全无感。第四是权限可控。技能天然是一个权限边界。你决定某个 Agent 能用哪些技能就等于决定了它能触达哪些系统、哪些数据这比裸给一堆工具要安全得多。1.3 技能粒度怎么定拆多细才不踩坑粒度是 agent-skills 设计里最容易翻车的地方。拆太粗技能变成一个“瑞士军刀”什么都能干但什么都干不好模型也容易误触发拆太细Agent 每一步都要现场编排等于退化回裸工具模式。我的经验是四个字按动作拆不按函数拆。用户的心智模型是“我要一份周报”所以“生成周报”是一个技能而不是“读取日历”“汇总任务数据”“排版输出”三个技能。反过来如果硬要把“写邮件内容”和“发送邮件”合成一个技能那么用户只是想让 Agent 帮忙润色一段文字时也会误触发发送动作这个风险就大了。判断标准其实就一条这个技能能不能被独立描述、独立测试、独立复用到其他场景。能就拆不能就合。粒度过粗反面粒度合适正面粒度过细反面收件箱管理读取、分类、回复、归档一把抓生成邮件回复草稿读取单封邮件正文难以复用极易误操作可独立测试、独立调度模型每次都要自己编排多步出错了不知道是哪个环节的问题内部最多两三层逻辑日志清晰上下文和调用次数翻倍1.4 技能与工具的关系技能是在工具之上加了一层编排再强调一下技能不是替代工具它是在工具之上包了一层“编排 规整”。工具做的是原子操作技能做的是“决定用什么工具、按什么顺序用、拿到结果后怎么整理”。一个典型的例子是天气查询。底层工具是“调用天气 API 获取某城市的实时数据”而技能可以是“根据用户的一句话判断出城市和时间调用天气 API再把温度、湿度、风力整理成适合口语播报的一句话”。同样一个工具不同的技能编排产出的体验完全不一样。这就是 agent-skills 的核心价值所在——它把模型从“每次都要临场发挥”解放成“按套路高效执行”。2. 技能定义的接口设计与实现要点2.1 manifest一份给模型看的“说明书”每个技能我都习惯用一个目录加一个 manifest 文件来管理。manifest 可以是 YAML 也可以是 JSON用来声明技能的所有元信息。下面这个例子是我常用的结构做了一个联网调研技能name: web_research version: 2.1.0 description: 针对某个主题做联网资料调研输出标注来源的要点摘要。适合竞品分析、技术调研、行业动态跟踪。不适用于数学计算、代码执行、本地文件操作。 input_schema: type: object properties: topic: type: string description: 调研主题越具体越好 max_sources: type: integer default: 5 required: - topic output_schema: type: object properties: summary: type: string description: 提炼后的调研要点 sources: type: array items: type: string description: 信息来源 URL 列表 steps: - search_web - fetch_page - extract_content - generate_summary这个文件里的字段没有一个是多余的。name 用于日志和监控version 用于灰度发布和回滚description 是给模型看的input_schema 和 output_schema 是给模型和下游代码共同看的steps 是技能内部的执行流程说明。2.2 description 怎么写模型才听得懂这是我最想强调的一点description 是给模型做意图匹配用的不是给人看的。很多项目里 description 只写一句“用于搜索”结果 Agent 在需要算数、需要总结、需要翻译时都想去调搜索技能调用准确率惨不忍睹。正确做法是把触发条件、典型场景、不适用场景都写进去。比如上文例子里那句“不适用于数学计算、代码执行、本地文件操作”就能帮模型排除一大批误调用。别小看这一句否定描述它往往比正面描述更能拉起准确率。我踩过一个很典型的坑把一个“数据可视化”技能的 description 写成“根据数据生成美观的图表”结果用户让 Agent “帮我看看这份数据有什么问题”时Agent 也去调用了图表技能生成了一张和问题无关的图。后来我把描述改成“仅当用户明确要求生成图表折线图、柱状图、饼图等时调用数据分析与解释请使用 data_analysis 技能”误调用率掉了一多半。2.3 input_schema 越严格Agent 越不容易出错模型调用技能时对参数类型非常敏感。你定义一个 string 字段模型传了数字下游代码直接炸你忘了给可选项设默认值模型每次都要猜猜错了就报错。所以我的建议是字段能给默认值就给 default非必填项千万别放进 required能枚举的尽量给 enum字段 description 写清楚格式要求比如“YYYY-MM-DD”。再提供一个细节不要一次定义特别多参数。参数越多模型生成正确参数的概率越低。超过五个参数时我就开始考虑是不是技能拆得不够细或者是不是应该把几个参数合并成一个对象结构。2.4 技能注册与动态调度别把所有技能都塞进上下文技能库建好之后需要一个注册中心来管理技能的加载、版本、启停状态。Agent 启动时把可用的技能列表注入上下文由模型在对话过程中根据用户意图做动态调用。这里最忌惮的做法是把全部技能一次性塞进提示词。原因有两个。第一上下文窗口有限技能描述太长会挤压对话记忆空间导致模型“记不住”用户前面说过的话。第二技能太多模型会“选择困难”误调用的概率飙升。我实测过一组数据一次对话中注入 30 个技能描述模型正确调用率大约 87%只注入与当前场景相关的 8 个技能调用率能提到 96% 以上。所以调度机制一定要支持按场景预筛。比如用户说“给老板发周报”那就先加载周报生成、邮件发送这两个技能其他技能不进上下文。不少框架现在都支持这类动态工具注入原理都是先做一轮场景识别再决定往上下文里放哪些技能。2.5 技能嵌套要不要让技能调用技能这是 agent-skills 的进阶设计。一个技能内部其实可以像个微 Agent先执行调研再根据中间结果判断要不要补充搜索词最后汇总输出。也就是说技能内部可以有自己的小循环。但我要提醒一句技能嵌套过深会让系统变得极难排查。日志里全是“技能 A 调了技能 B技能 B 又调了技能 C”一旦出问题你根本定位不到是哪一环挂了。我的建议是最多两层顶层技能负责编排内部的子技能只做单点动作不允许子技能再往下调。超过两层排查成本和 token 消耗都会成倍上升。3. 从零搭建 agent-skills 的完整实操流程3.1 第一步盘点手头的能力资产标注稳定度先别急着写代码。把现有系统的能力全部列出来包括内部 API、第三方服务、代码库里可复用的函数、数据库查询接口。每项能力写清楚三件事能做什么、输入是什么、输出是什么。拿个表格记就行。我建议在列表时顺手标注“稳定度”这项能力是长期稳定提供的还是临时 hack 出来的不稳定的能力不要封装成技能否则 Agent 会非常忠实地把你的 bug 复现一百遍。我见过一个团队把内部临时脚本封装成了技能结果那个脚本本身依赖一个写死的临时目录Agent 一调用就报错用户还以为 Agent 坏了。3.2 第二步按业务域设计技能目录结构技能目录建议按业务域划分research/、communication/、data_process/、ops/、写作/、翻译/ 等等。每个目录下再按动作细分。这个结构本身就是一套组织边界后续做权限控制、做灰度发布都可以按目录来切。例如skills/ research/ web_research.yaml pdf_analysis.yaml communication/ email_reply.yaml meeting_summary.yaml data_process/ data_cleaning.yaml chart_generation.yaml目录命名要克制不要搞出几十个顶层分类。我的经验是顶层分类保持在五个以内超过五个就要开始审视是不是分类过细了。3.3 第三步实现技能的三段式骨架先写 manifest再写内部实现。内部实现我统一封装成“输入校验 → 执行步骤 → 输出规整”三段式。输入校验放最前面避免脏数据进流程。这一步很便宜但能挡掉一大半线上问题。执行步骤是技能真正干活的地方内部可以调用多个工具也可以有一个小循环。输出规整放最后保证 Agent 拿到的结果是结构化的不是一坨原始文本。我用一个数据清洗技能的简化版本说明代码是 Pythondef clean_data(raw_text: str, rules: list[str]) - dict: # 第一段输入校验 if not raw_text or not len(raw_text.strip()): raise SkillInputError(raw_text 不能为空) if not rules: raise SkillInputError(rules 不能为空) # 第二段执行步骤 cleaned apply_rules(raw_text, rules) # 内部逐条执行清洗规则 # 第三段输出规整 return { cleaned_text: cleaned, applied_rules: rules, status: success, chars_before: len(raw_text), chars_after: len(cleaned), }这个例子里的输出规整就很有意思。chars_before 和 chars_after 这类统计字段看起来是给日志用的其实也是给模型用的——模型拿到这些字段就能向用户解释“我帮你把文本从 5000 字压缩到了 3200 字删掉的全是重复表述”体验完全不一样。3.4 第四步给每个技能写三组测试用例这一步最容易被砍但恰恰是技能体系能不能长期维护的分水岭。每个技能至少要有三组测试正常用例、边界用例、异常用例。正常用例覆盖主流程给一个合理输入验证输出结构完整、内容正确。边界用例覆盖空输入、超长输入、特殊字符、缺失字段。异常用例覆盖依赖服务挂掉、网络超时、外部 API 返回格式不对等场景。拿邮件回复技能举例正常用例是“给客户回一封说明延期的邮件”边界用例是“没有任何上下文只有收件人地址”以及“邮件正文超过一万字”异常用例是“发件服务返回 500技能内部应该返回一个什么样的错误信息给 Agent”。这三组用例写全了技能上线之后你才敢放心交给模型。3.5 版本管理与灰度发布技能也是要迭代的。版本号建议遵循语义化版本规则大版本号变动代表接口变化小版本号代表内部逻辑优化。发布上我习惯先让新版本技能在测试环境跑一轮评测再在线上对少量流量开启观察调用成功率和用户反馈最后全量。虽然技能不像模型那样有复杂的评估体系但“改一个 prompt 把效果改差了”这种事情在实际项目中太常见了没有灰度就会直接被用户教做人。4. 常见问题与排查技巧实录4.1 模型就是不调用我想要的技能这大概是最常见的投诉。排查顺序我建议是这样的先看 description 是否准确表达了触发场景再看输入参数是否必填过多最后看是不是同场技能太多导致模型选择困难。参数这条我多说一句。必填参数越多模型调用意愿越低。因为模型本质上是想“多快好省”地完成任务它发现调用你这个技能要凑齐五个参数而另一个技能只要一个参数它就会倾向于选那个简单的。所以能做成默认值的参数绝不设为必填。我自己踩过最典型的一次是技能 description 写得太“文绉绉”比如“协助用户完成信息检索任务”模型没理解这到底什么时候该用结果把任务交给了一个语义相近但能力不符的技能。改成“当用户要求查找资料、搜索网页、查询最新信息时调用”这种大白话之后调用率立刻就上来了。4.2 技能调用成功但返回结果不对技能被调用了也执行了但模型拿到的结果不是想要的。这时候八成出在输出规整环节。很多实现会把工具原始返回直接丢给模型中间少了一层字段映射和格式约束。解决办法是两层第一层在技能内部做规整保证输出符合 output_schema第二层在技能外部加一道输出校验发现不符合 schema 就触发一次内部重试重试仍失败就直接返回 failed 状态不让脏数据流入模型。4.3 技能执行到一半失败Agent 不知道怎么办这个问题最隐蔽也最影响体验。技能内部第三行调用的接口超时了或者中间某一步返回了异常格式Agent 拿到的是一段堆满错误的输出于是它开始胡编乱造给用户一个看似合理但其实完全错误的结果。我的解决方案是统一错误语义。所有技能输出里都带 status 字段取值只有三种success、partial、failed。partial 表示部分成功比如搜索结果拿到了但有一个网页打不开failed 表示主流程失败。Agent 拿到 partial 就知道可以继续做后续处理拿到 failed 就知道应该向用户解释失败原因或者换一个方案。模型是能读懂这种结构化状态的前提是你把语义定义清楚、写进技能文档里。4.4 技能多了以后启动慢、上下文爆、调用乱技能数量一多三个问题会同时冒出来启动时加载慢、上下文被技能描述挤爆、模型误调用率上升。我的解法是两条腿走路懒加载加场景预筛。懒加载是指技能实现不在启动时全部载入内存只有在被调度时才真正加载manifest 元信息可以常驻内存供注册中心做预筛查询。这样技能库从 20 个涨到 80 个启动时间几乎没有变化。场景预筛则是根据用户当前对话内容先把候选技能集合缩小到 5 到 10 个再把这些候选技能的 description 注入上下文。这一步可以用模型做轻量意图分类也可以用简单的关键词规则先粗筛。两种方式我都试过关键词规则便宜但误判多模型分类准确但多一次调用你可以按业务体量权衡。下面把高频问题整理成一个速查表方便你排查时直接对号入座现象优先排查项常见解法模型不调用技能description 是否准确、必填参数过多重写 description减少必填参数调用成功但结果不对输出规整缺失、schema 未校验加字段映射加输出校验执行一半失败错误语义不清晰统一 statussuccess / partial / failed技能多了就乱全部注入上下文懒加载 场景预筛技能 A 误触发description 边界没写清明确写“不适用于哪些场景”5. 一些个人经验以及后续还能往哪走做了一年多技能体系我最大的体会是这事七成的收益来自设计而不是编码。技能的边界划清楚、description 写准确、错误语义定明白你就已经赢过大多数人。剩下的三成是工程实现而工程实现里最值钱的又是测试和监控。最后分享一个小技巧给每个技能加一个 usage_count 统计位记录被调用的次数和成功率。没人用的技能先放着不急着优化被高频调用的技能花更多心思打磨它的细节比如加权重、做多策略分支、针对失败案例补测试。过段时间你会发现真正被 Agent 频繁使用的技能就那么几个把它们的质量做到极致比无限新增技能有用得多。后续想往深走的方向一个是让技能具备自我修复能力从失败日志里自动归纳问题并给出修改建议另一个是建立技能间的依赖图和冲突检测避免两个技能对同一任务“抢活”。这两个方向都还比较新坑也多等有阶段性成果了再来跟你细聊。