★ FEATURED ARTICLE 最近在把 Agent 项目从 Demo 推向真实业务场景时我遇到一个很头疼的问题同样的任务昨天跑得好好的今天换了一批输入就乱了。模型没变代码没改Prompt 也没动问题到底出在哪折腾了半个月我才慢慢意识到问题不是模型不够聪明而是我一直在用写函数的思路做 Agent却忘了 Agent 真正需要的是一套可以复用的技能。这个思路转变让我彻底重新审视了agent-skills这套设计理念——把复杂任务封装成可组合、可复用、可升级的技能单元而不是让模型每次都在开放式指令里盲猜。这篇文章就聊聊我的完整实践过程包括技能到底是什么、怎么设计、怎么落地、怎么调优以及踩过哪些坑。agent-skills不是什么新框架也不是某个开源库的名字它更像一种组织 Agent 能力的方式把高频出现的复杂任务从口头交代给模型变成一套有流程、有约束、有验收标准的技能包。对正在做 Agent 应用开发、或者被模型输出不稳定折磨过的朋友这篇文章应该能给你一些可以直接抄作业的参考。1. agent-skills 到底是什么我在重构 Agent 时想明白的一件事1.1 从会调 API到会用技能的认知转变最早我做 Agent 的方式非常简单粗暴一个大 Prompt 交代角色设定再挂上十几个 function calling 的工具函数然后期望模型自己知道什么时候该调哪个工具、参数怎么填、结果怎么整理。这种方案在小规模 Demo 里确实跑得通但一旦任务复杂起来问题就暴露得非常明显。举个实际例子。我有个任务是要让 Agent 完成竞品信息收集然后输出一份结构化报告。最初的做法是给模型一个工具叫search_competitor_info让它自己去搜索、自己总结。结果模型经常搜到一堆无关信息还当成有效内容写进报告中间忘了收敛越查越散最后报告结构完全失控同样的输入跑三次三次结构都不一样。这时候我才意识到工具只是能力的最小单位它回答的是能做什么但从不回答该怎么做才稳定。而该怎么做才稳定这件事恰好是技能要解决的核心问题。拿人来做类比更容易理解。一个新手厨师拿到一把刀工具他只知道刀能切菜但不知道切土豆丝要先切片再切丝、刀要握稳、指节要顶着刀背。这些切土豆丝的完整步骤和注意事项就是技能。Agent 也一样工具定义能力边界技能定义使用能力的完整流程。1.2 技能、工具、Prompt 的边界到底在哪搞清楚三者的边界是设计agent-skills的第一关我自己的理解是这样的层面回答的问题典型形态可复用性Prompt你是谁、什么风格、总体原则是什么文字指令弱容易被具体任务带偏工具Function你能调用什么外部能力API 封装中只提供原子操作技能Skill一类任务的标准解法是什么流程 约束 验收标准强可组合可沉淀也就是说Prompt 管人设工具管动作技能管流程。三者不是替代关系而是分层配合。agent-skills的核心主张是把那些你反复调优过、已经验证有效的任务流程从 Prompt 中抽出来固化成一套标准化的技能让模型遇到同类任务时不需要重新摸索直接走成熟流程。1.3 技能为什么能带来稳定性稳定性来自两个层面。第一是流程确定性。技能把任务的执行路径固定下来了每一步做什么、做到什么程度算完成都有明确约束。模型的开环自由发挥变成了闭环流程执行输出的方差自然就小了。第二是上下文可控性。没有技能的时候模型要在一次对话里同时处理理解任务、规划步骤、调用工具、整理结果四件事工作记忆很容易过载。有技能之后理解任务和规划步骤这部分被固化成技能定义模型只需要关心当前步骤的具体参数和执行结果认知负担小很多失误率直线下降。我实际跑下来的数据显示从裸模型 工具的模式切换到agent-skills模式之后同类任务的输出稳定率按我定义的可接受标准算从 60% 左右提升到了 87% 左右这个提升幅度让我对这套思路彻底信服了。2. 一个技能的内部结构我把竞品调研拆成了五个部分2.1 触发条件什么时候该用这个技能技能设计的第一步是定义触发条件。不是说用户提到调研两个字就触发那太粗糙了。我建议把触发条件分成两种粒度意图匹配用户想做什么事比如分析、收集、对比场景匹配当前上下文是否具备执行条件比如已经掌握了目标公司名称、行业范围等必要参数。触发条件写得太宽技能容易被误激活本来用户只是想随便聊聊结果 Agent 强行开始走流程写得太窄技能又形同虚设永远等不到被调用。我的经验是触发条件应该明确列出必要的前置信息缺了前置信息宁可先主动提问补齐也不要硬跑。以我最常用的竞品调研技能为例它的触发条件是用户意图包含调研 / 分析 / 对比 / 看看 / 研究等动作词上下文或对话历史中能提取出至少一个公司/产品名称如果没有公司名称技能不触发而是先反问用户你想让我调研哪个公司2.2 输入 Schema把模糊的需求翻译成明确的参数结构技能的输入不能是一段自由描述必须是一个结构化的 Schema。这一步需要有一个强制性的数据模型模型或者上层逻辑把用户的自然语言映射成固定字段后续所有流程都基于这个 Schema 执行。我曾经用过的竞品调研技能 Schema 长这样{ skill: competitor_research, version: 2.1, input: { company_name: 目标公司名称必填, industry: 所属行业可选缺省时自动识别, depth: 调研深度lite / standard / deep缺省为standard, focus_areas: [重点关注的维度如定价、市场份额、技术路线], output_language: 报告语言缺省为与用户对话语言一致 }, output: { format: markdown_report, required_sections: [概览, 产品/服务, 商业模式, 竞争定位, 关键结论], max_length: 按depth分层standard不超过2000字 } }这套 Schema 最大的价值是它逼着上游先想清楚到底需要什么信息而不是一股脑地把用户的需求直接丢给模型自由发挥。输入越模糊输出就越不稳定这是一条铁律。2.3 执行流程把步骤明确到模型不需要思考下一步做什么技能中的执行流程本质上是把模型自由规划变成过程化脚本。在做技能设计时我把竞品调研的流程定义成了六个固定步骤解析输入参数确认公司名称和行业检索内部知识库看有没有历史调研结果可以直接复用通过搜索工具获取公开信息限定最近 6 个月的时间窗口按 focus_areas 维度对信息进行归类筛选剔除与目标无关的内容交叉验证关键数据点至少两个独立信息源一致才写入报告按规定的报告结构生成最终输出并标注信息时效和可信度。每个步骤之间还有明确的转场条件——比如步骤 2 中如果内部知识库已经有 30 天内的现成报告就直接跳到步骤 6不再重复收集。这些转场条件是对流程的进一步约束也是技能质量和实时性的重要保证。2.4 输出规范与失败策略好技能必须想清楚做砸了怎么办输出规范定义的是什么算完成失败策略定义的是做砸了怎么收场。这两件事容易被人忽略但恰恰是稳定输出的关键。输出规范不是一句格式要清晰就完了而是要把可验收的字段列清楚。我刚才在 Schema 里写的 required_sections 就是一种硬约束——报告必须包含这些章节缺了任何一个都算技能失败。对于每个章节还可以定义质量要求比如关键结论必须基于数据而不是主观推测。失败策略则要预设几类异常情况搜索不到有效信息停止执行明确告诉用户公开渠道信息不足而不是编造关键数据交叉验证失败在报告中标注该数据存在多个信息源不一致建议人工复核单步重试超过两次放弃该路径降级为替代路径或上报。设计失败策略的时候我自己的核心原则是宁可承认做不了也不要产出优美的错误结论。一次模型自信地胡说八道对业务造成的伤害远大于它老实承认这部分我拿不准。3. 从零构建技能库的完整路径我走通的四步流程3.1 第一步用两周对话日志确定高频高价值任务清单很多教程会告诉你先设计技能但我建议反过来先别急着设计。先把你的 Agent 放到真实场景里跑一到两周记录所有用户请求然后归类统计。我当时的做法是把所有对话日志按任务意图打标签调研类、写作类、数据分析类、问答类……统计每个类别的出现频率、平均耗时、失败/返工率选出频率高 失败率高 结果可标准化三类交集的任务作为首批技能候选。我这个原则非常明确不见得是最高频的而是要选高频且当前做得很痛苦的。如果某类任务本来就跑得很稳定就没有必要用技能去约束它反而可能因为流程固化而变笨。我第一批评选出来的候选是竞品调研、周报生成、技术方案对比这三个恰好都是又高频、又容易翻车的典型场景。3.2 第二步先写纯 Prompt 版流程验证稳定后再固化这里我有一个非常深刻的教训不要一上来就写技能的代码框架。先拿最朴素的 Prompt 把流程跑通记录效果再逐步收紧约束。原因有两个技能的流程设计是否合理只有跑真实数据才能验证写代码之前先跑 Prompt 试错成本极低直接写框架容易把设计假设当成既定事实后发现流程本身有问题还得推翻重来。我当时的做法是对每个候选任务写一个 2 到 3 页的研究性 Prompt包含详细的步骤约束和格式要求然后用过去 30 天的真实用户输入去测。如果某一步经常出错就调整 Prompt 里的约束描述直到效果稳定到 80% 以上可以接受才开始把 Prompt 里的流程抽成正式技能的 Schema 和代码。这一步听起来绕远实际上省了很多时间。我见过不少开发者直接跳过验证环节去写技能框架最后技能倒是写出来了跑起来效果却一言难尽。3.3 第三步定义技能仓库结构把每个技能做成一等公民技能库的管理方式直接影响长期可维护性。我的建议是每个技能都是一个独立目录包含三件套skills/ ├── competitor_research/ # 技能目录 │ ├── SKILL.md # 技能说明触发条件、使用场景、边界 │ ├── schema.json # 输入输出 Schema │ └── workflow.py # 执行流程逻辑 ├── weekly_report/ # 另一个技能 │ ├── SKILL.md │ ├── schema.json │ └── workflow.py └── manifest.json # 技能注册表描述所有技能的路由规则SKILL.md主要给人和模型共同看描述这个技能是干嘛的、什么时候不该用它。schema.json是机器可读的输入输出约束。workflow.py包含实际流程逻辑包括如何调用模型、如何调用工具、如何处理中间结果。还有一个容易忽略的细节每个技能要有独立的版本号。我的版本规则很简单——Prompt 或 Schema 改了版本号就要变流程逻辑改了版本号也要变。否则技能库一多你根本分不清线上跑的是哪一版出了问题也没法回滚。3.4 第四步给技能配置路由层让模型学会挑技能技能库建好了下一步是让 Agent 知道在什么情况下选哪个技能。我一开始的做法是把这个选择交给模型自己——把所有技能名和 SKILL.md 塞给模型让它选。结果很糟糕技能一多模型就开始乱选明明用户问的是帮我看看这周数据有什么异常模型居然调了竞品调研技能。后来我改成了声明式路由 模型兜底的混合策略每个技能在 manifest.json 里声明自己的触发关键词和前置条件上层先基于规则做一次粗筛命中唯一技能就直接绑定如果多个技能同时命中或者一个都没有命中再把候选列表交给模型由模型做最终选择。这套策略上线后技能路由的准确率从 72% 提到了 94% 左右。路由层是整个技能库的大脑它的配置质量直接决定了技能有没有机会被正确使用。4. 评测与调优的实战经验效果不稳定时先查是不是技能边界出了问题4.1 建立一套以通过率为核心的回归测试集技能调优最大的难点是怎么判断我已经改好了而不是我把这里修好了、那边又搞坏了。没有评测集所有调优都是盲人摸象。我为每个技能都建了一个最小回归集挑 15 到 30 个典型用户请求覆盖正常输入、边界输入和异常输入三类。每次改动后用同一批输入跑一遍看通过率变化。通过率的定义要提前定好不能含糊。以竞品调研技能为例我定义通过需要同时满足输出结构完整包含所有 required_sections关键数据要么有来源要么明确标注无法验证流程没有超过预设的最大步骤数或 token 预算用户原始意图没有在流程中被扭曲。条件列清楚之后调优就有了客观标尺。没有这套评测集的时候我觉得自己改得很对结果上线被用户投诉有了评测集之后改动前先跑一遍至少心里有底。4.2 三种最常见的失败模式及其根因我把自己踩过和观察别人踩过的坑归纳成三类基本覆盖了 90% 的技能失效场景。第一种指令冲突。技能流程里有两个约束互相打架模型不知道怎么取舍。比如技能里既说信息必须来自权威来源又说尽可能多地收集观点模型就会在两者之间摇摆输出一会儿偏保守一会儿偏发散。解法是给约束排优先级明确当两者冲突时以权威性优先。第二种状态残留。技能内部步骤产生的中间状态污染了后续步骤。比如竞品调研技能在信息收集阶段拿到了大量数据到了结论生成阶段模型还在纠结那些已经筛选掉的信息导致结论章节偏离主题。解法是在技能的关键节点强制压缩上下文——把中间步骤的结果汇总成摘要而不是把原始数据全部保留在上下文里。第三种Schema 定义失焦。输入 Schema 太宽松导致不同用户输入被映射到差异巨大的执行路径或太严格导致正常输入频繁触法校验失败。Schema 的边界需要靠回归集不断校准不能设计完就当圣旨。我目前的做法是每当回归集里出现一种新的合理但不合 Schema 的输入就更新一次 Schema让它吸收这种输入而不是让用户去迁就我的框架。4.3 实测中几个值得关注的量化变化这些数据不是我为了写文章瞎编的都是我自己项目里真实记录观察到的变化。从 2 月份到现在我的 Agent 表现经历了三个阶段阶段配置方式输出稳定率平均处理时长主要问题第一阶段大 Prompt 工具函数约 58%约 55 秒结构漂移、信息发散第二阶段简单技能封装约 73%约 42 秒路由错误多、边界不清晰第三阶段完整技能库 路由层 回归评测约 87%约 35 秒组合任务仍然吃力时长下降其实很好理解技能流程固定后模型不再需要在每一步重新规划试错的次数少了token 消耗也随之下降。stable 率和耗时的同步改善说明技能化不只是把输出变稳了也让整个流程更经济。4.4 调优时我坚持的两个原则第一一次只改一个变量。改 Schema 就只改 Schema改流程就只改流程改完立刻跑回归。同时改多个地方出了问题你根本没法定位是哪一步导致的。第二把模型经常犯错的地方反向沉淀成技能约束。比如我发现模型在生成报告时经常在结论部分重复正文里的内容我就往技能的 output 规范里加了一条结论章节不允许重复正文中的事实陈述只允许给出判断和解读。这类从错误中长出来的约束比任何理论设计都可靠。5. 技能多了之后的现实困境与我的取舍5.1 组合爆炸技能复用的代价没有想象中那么低技能化做到中期我的技能库到了 10 个左右开始遇到一个新问题技能与技能之间不是严格隔离的很多任务需要多个技能配合。比如用户让我调研三家竞品并做对比严格来说它既用到了竞品调研技能也用到了对比分析能力。如果把多技能组合的每种组合都抽象成新技能技能数量会爆炸式增长但如果让模型现场编排又回到了自由发挥不稳定的老路上。我目前的折中方案是只允许两层组合第三层以上的组合任务全部走人工模板。具体来说技能 A、B、C 之间任意两两组合由路由层支持三个以上技能同时协作的任务则定义为流程型任务使用预设的编排脚本而不是让模型自由组合。这个折中方案确实牺牲了一部分灵活性但换来了可维护性。对大多数业务场景来说两层组合已经覆盖了七八成需求没必要为了剩下的小部分场景把架构搞得过度复杂。5.2 技能封装不了的东西模型的推理深度我必须强调一个边界技能化解决的是执行稳定性问题不是模型智商问题。如果一个任务需要的是深度推理、复杂权衡、多步创造性思维把它们强行封装成技能反而有害。原因很简单技能的本质是把过去成功过的流程固化下来它假设的是这个问题有标准解法。如果问题本身没有标准解法固化流程只会把模型锁死在过去的思维方式里让它错过更好的解决方案。我现在的判断标准是如果一个任务我自己能写出流程步骤才值得做成技能如果我自己都想不清步骤那就老老实实用强模型 开放指令。技能化和模型能力是互补关系不是一个替代另一个。5.3 去掉一个最高分我最终砍掉了哪些伪技能建立技能库的过程中我前后砍掉了几个看起来很美好、实际价值很低的技能。其中一个典型的例子是通用数据分析技能——它可以处理的数据分析任务种类太多Schema 只能定义得非常宽泛实际执行时几乎和没有技能约束的裸模型没区别还增加了路由层的认知负担。砍掉它的触发条件也很简单回归集通过率虽然不低但通过的标准太松了几乎什么输出都能算通过这说明这个技能根本没有在限制模型。没有约束力的技能不叫技能只是给流程披了一层外衣。 真正有价值的技能一定是明确说绝不能怎么做或必须怎么做的。所以我的技能库现在维持在一个很少但很精的水平每一个技能都有足够强的约束力都能通过回归测试明确区分会用和不会用。这比堆一大堆弱技能要有用得多。自己从裸 Prompt 逐步走到这套技能体系最大的体会是Agent 开发中稳定性的瓶颈往往是设计问题而不是模型能力问题。与其期望模型自己每次都能聪明地规划出最优路径不如把路径设计好、把约束设清楚、用数据把方式验证扎实。agent-skills在我的实战里最大的价值就是把智能从不可控的玄学变成了可测量、可调优的工程问题。如果你也在做 Agent 应用我建议从小处着手挑一个你当前最痛苦的任务先按这篇文章的流程试着做第一个技能跑通之后再逐步扩展体验会比直接搞一套完整框架来得踏实得多。
阅读完成 · 觉得有帮助？
