前阵子有个做 AI 应用的朋友找我吐槽说他搭的 agent 总像个什么都懂一点的实习生——写代码也行、查资料也行、整理文档也行但每一件事都做得不够专业稍微往深了问就露怯。他想让 agent 在特定任务上达到老手的水准却不知道该从哪下手。我当时就告诉他你缺的不是更聪明的模型而是一套成体系的agent-skills机制。这句话不是随口说的。过去大半年我一直在折腾 agent-skills 这套思路把原本堆在 system prompt 里的一坨通用指令拆成了一个个独立、可复用、可单独测试的技能单元。做完之后最直观的感受是agent 不再是一个靠临场发挥的通才而是变成了一个带着一堆专业工具书、知道什么场景该翻哪本书的行家。这篇文章我就把这段时间的完整实践串一遍包括 agent 和 skills 之间到底隔了什么、一个 skill 文件该长什么样、怎么写才能让模型稳定调用、多技能共存时怎么调度、以及怎么测试才能保证上线不翻车。如果你正在做 agent 应用或者只是好奇让模型干专业活这件事到底怎么落地这篇文章应该能给你点实在的东西。1. 先搞清楚一个前提agent 和 skills 之间到底隔了什么1.1 为什么要把指令拆开而不是堆进去很多人做 agent 的第一反应是把所有要求写进一个巨大的 system prompt你是我的助手你要做 A做的时候注意 B遇到 C 情况要 D输出格式要 E……写到后面prompt 三千字起步模型的表现却越来越飘。为什么因为模型的注意力是有限的指令太多、优先级不明确的时候它只能抓主干、丢细节而那些细节恰恰是你最在乎的专业要求。agent-skills 的核心逻辑恰好相反不追求一个全能的 prompt而是把每一个专业任务封装成一个独立的 skill每个 skill 只负责一件事只有被触发时才进入上下文。这样做有三个立竿见影的好处一是单个 skill 的指令可以写得很细、很专不用担心稀释模型注意力二是不同任务之间的指令不会再互相干扰三是每个 skill 可以单独迭代、单独测试哪个出了问题就修哪个不用动整条链路。1.2 工具、技能、工作流三个概念别混在一起开始设计 skill 之前还有一个特别容易踩的概念坑把工具tool、技能skill和工作流workflow当成一回事。实际上它们是三个层次的东西混在一起会直接导致你的 skill 目录设计得一团乱。拿一个做数据分析的 agent 举例。工具是能做什么比如有 execute_python、read_csv、visualize 这些函数它们给 agent 提供了操作能力。技能是知道怎么做比如做探索性数据分析这个 skill它包含一套步骤——先看数据形状、再查缺失值、然后看分布、最后做相关性分析这套步骤是可以沉淀下来反复用的。工作流则是什么时候做什么比如每周一自动拉取上周的销售数据跑一次 EDA出一份周报它把多个技能和决策条件串成了一个完整流程。很多人的 skill 目录之所以越用越乱就是因为在设计 skill 时不小心把工具定义和工作流逻辑也塞了进来。我的原则很简单skill 里只写怎么做好一件事不写用什么函数也不写什么时候该做这事。工具是底座工作流是编排skill 是中间那层可被排列组合的专业能力单元。2. 一个 Skill 的标准解剖从入口描述到执行指令如果你去看各种开源 agent 框架里的 skill 实现会发现格式五花八门但核心部件都差不多。我自己用下来一个成熟的 skill 文件至少应该包含四块name、description、params、instruction。前两块决定模型什么时候想起它后两块决定模型调起它之后能不能干好活。2.1 模型靠什么判断该不该用这个技能很多人在 skill 的 description 上敷衍了事写一句用于代码审查就完事了。结果是什么模型在真正需要它的时候想不起来或者在不该用的时候强行调用。这是因为在大多数 agent 架构里模型决定是否激活某个 skill靠的就是读 description 然后做语义匹配。它不看你的 instruction 写得有多精彩只看你那几句话能不能和当前用户请求挂上钩。所以 description 的写法核心就一句话把什么时候该用本技能的触发条件写清楚。我个人的习惯是三段式第一句说这个 skill 是干什么的第二句列举哪些说法应该触发它最好是用户原话级别的例子第三句明确哪些情况不应该触发把边界画出来。举个例子一个代码审查技能如果 description 里写用户要求审查代码、检查代码质量、做 code review 时使用不要用于 debug 场景触发准确率会比一句话描述高出一大截。2.2 参数声明给模型的输入边界params 是容易被新手忽略的部分。skill 不是凭空运行的它需要输入这些输入从哪里来在 agent 场景下通常是模型根据对话内容自主抽取。如果 params 定义得不清晰模型要么抽错要么漏抽skill 拿到的数据就是残缺的。这里有一个很实用的建议给每个参数写清楚它的含义、类型、是否必填以及从哪类信息里提取。比如一个会议纪要整理的 skill输入参数可以定义为 meeting_transcript必填字符串用户粘贴的会议文字记录和 attendees可选字符串列表会议参与人。模型读到参数说明后才知道该从对话里找什么。另外参数不要设计得太多。我见过有人一口气定义十几个参数结果模型光是抽取参数就耗尽了大半上下文预算skill 本身的执行质量反而下降。参数数量控制在 3~5 个是比较健康的范围。2.3 执行指令的三种写法与适用场景instruction 是 skill 的灵魂也是写法差异最大的地方。我总结了三种常见写法各有各的适用场景。第一种是步骤式适合流程固定的任务。比如数据清洗第一步检查重复值第二步处理缺失值第三步统一字段类型第四步输出清洗报告。这种写法胜在稳定模型照着走基本不会跑偏缺点是灵活度低遇到特殊情况容易僵化。第二种是原则式适合需要判断力的任务。比如内容审校不要逐字逐句改稿先看逻辑结构再看措辞对事实类错误必须标注来源修改要保留作者语气。这种写法不告诉模型具体怎么走而是给它几条必须遵守的底线让它自由发挥的同时不越界。第三种是示例式也就是 few-shot适合输出格式复杂、难以用规则描述的任务。比如生成结构化周报给出两三个标准的输入输出对模型会照着模仿比写十行你必须怎么怎么样有效得多。这三者也可以混用。我的经验是核心流程用步骤式兜底专业性要求用原则式围栏复杂输出用示例式做示范三层组合起来skill 的质量就有了基本保障。2.4 版本号与元信息容易被忽视的两样东西最后聊一个很多人不重视、但后期会救命的东西版本号和元信息。skill 是会迭代的今天你改了 description明天你调整了输出格式如果不记录版本两周后 skill 表现异常你根本不知道是哪个改动引起的。我现在的习惯是每个 skill 顶部都维护 version、changelog、owner 三个字段改动一次就更新一次。这不是形式主义是在多技能、多协作场景下做问题回溯的唯一线索。3. 手写一个实用 Skill从代码审查到完整落地讲完了理论用一个实例把整个流程走一遍。我选代码审查这个任务因为它是典型的看起来简单、做好很难的技能人人都能说两句但说出来的话必须专业、有依据、可执行才称得上 skill。3.1 选一个值得做成 skill 的任务不是所有任务都适合做成 skill。判断标准有三条第一任务是重复出现的至少每周都会碰到几次第二任务有相对稳定的方法论不是每次都不一样第三任务做得好不好有明确的评价标准。代码审查三条全占所以特别适合。第一步是把这个任务的方法论沉淀下来。我当时回顾了自己做过的几十次 code review梳理出了一个固定框架先通读理解整体设计再按正确性、安全性、性能、可维护性四个维度逐项检查最后按严重程度分级输出问题清单。这套框架就是 skill 的核心资产。3.2 Skill 文件的完整示例下面是我实际用过的一个代码审查 skill 的简化版格式是 YAML字段按照前面说的四件套来组织name: code_review description: 对给定的代码片段进行系统性审查输出结构化审查报告。 当用户说帮我看看这段代码、做一下 code review、 检查代码有没有问题、审查这个 PR时使用本技能。 不要用于单纯的语法报错排查也不要用于 debug 类问题。 version: 1.3.0 params: code: type: string required: true description: 待审查的代码文本可以直接从对话内容中提取 focus: type: string enum: [correctness, security, performance, readability] required: false description: 审查重点缺省时四个维度全查 instruction: | 1. 通读全部代码先建立整体认知不要看到第一个可疑点就下结论。 2. 如果指定了 focus优先审查对应维度未指定则按正确性、安全性、 性能、可维护性的顺序逐项检查。 3. 判断每个问题的严重级别blocker会导致功能错误或安全漏洞、 major明显影响质量、minor一般性改进建议、nit风格类小问题。 4. 按以下格式输出报告 【概览】代码行数、函数数量、主要职责 【问题清单】按严重级别从高到低排列每条包含 - 位置行号/函数名 - 问题描述 - 为什么是问题 - 建议修改方案 【总体评价】2-3 句话涵盖代码质量和改进优先级。 5. 规则没有充分依据不下结论每条问题必须给出位置和理由 如果代码行数超过 300 行按函数为单位分批审查不要试图一次看完。3.3 第一次运行后的迭代方向写完 skill 文件千万别直接投入使用先跑三轮测试。第一轮拿一个你知根知底的旧代码来测因为你清楚里面埋了什么问题能判断 skill 有没有找到第二轮拿一段故意写得很烂的代码看它会不会过度报告第三轮拿一段高质量代码看它会不会为了凑数而硬报问题。我第一版 code_review skill 跑下来的问题非常典型它会报告一些看似是问题、其实不是的东西比如对局部变量的命名提出风格修改而这种建议对团队项目毫无价值。后来我在 instruction 里加了一条规则nit 级问题如果数量超过 5 条只报告最有代表性的 3 条并强调对团队既有代码风格要克制。这就是 skill 迭代的常态——不是一步到位而是通过真实反馈一点点调优。4. Skill 编排与路由多技能共存时的调度细节单技能跑通只是第一步。当你的 agent 里挂了十几个甚至几十个 skill 时真正头疼的问题才开始出现模型能不能在正确的时机选择正确的技能两个技能描述相似时怎么办技能之间能不能互相调用4.1 描述冲突两个 skill 都觉得自己该上场我踩过的最痛的一个坑是有一次同时维护了周报生成和项目进展总结两个 skill前者负责把零散工作记录整理成周报后者负责从长篇讨论中提炼项目状态。结果模型经常在用户说帮我写周报时反而激活了项目进展总结输出一份文不对题的东西。问题出在 description 的语义边界不够清晰。解决方式有两个层面。第一在编写阶段就刻意做差异化描述每个 skill 的 description 里都明确写出本技能不适用于什么场景把重叠区域提前隔离。第二在路由阶段引入优先级机制如果两个 skill 的匹配分数都很高优先选择 description 更具体、更长的那一个——因为描述更具体往往意味着它更贴近用户的真实意图。我后来干脆把两个技能合并成一个在 instruction 里用条件分支处理两种场景反而更清爽。同类技能能合并就合并合并不了的才靠描述区分这是减少路由冲突的治本方法。4.2 技能链A 技能里调用 B 技能有些复杂任务天然需要多个技能协作。比如写一份竞品分析报告可能需要先调用网页信息采集技能抓取资料再调用数据分析技能做对比最后调用报告生成技能输出文档。这就涉及技能链的设计。技能链有两种实现思路。一种是在 skill A 的 instruction 里直接写本技能执行第三步时需要调用 skill B调用方式是……把依赖关系硬编码进去。这种方式简单直接但耦合度高A 一改B 被影响的概率就大。另一种是解耦思路让每个 skill 只输出结构化中间结果由上层 agent 根据中间结果决定下一步调用哪个技能。比如竞品分析技能只负责输出竞品功能对比表至于这张表是拿去生成报告还是生成 PPT它不关心。我个人强烈倾向第二种。因为第一种做法本质上还是在写死流程违背了 skill 设计的初衷——可复用、可组合。把中间结果结构化等于把技能之间的耦合点变成了数据这条数据流比任何硬编码都更稳定。4.3 上下文与预算问题多技能共存还有一个隐性问题上下文窗口。每个 skill 一旦被激活它的 instruction 就会占据上下文空间如果 agent 在一个长对话里连续激活四五个 skill光是指令就吃掉不少 token留给实际内容的就不多了。我的做法是给 skill 的 instruction 设定一个400~600 token 的预算上限。写的时候如果超了就砍掉非核心的细节或者把细节挪到外部知识库里skill 里只留关键路径。另外agent 框架最好支持技能用后即焚——完成当前任务后该技能的指令就从后续上下文中移除避免污染下一步操作。这个机制看起来很基础但没有它长会话场景下技能越多模型越容易精神分裂。5. 测试 Skill 的三种方式单测、集成验证与回归很多团队把 skill 写完就直接上线然后靠用户反馈来发现问题。这是最被动的做法。Skill 本质上是代码资产它应该享受和代码一样的测试待遇。5.1 单测验证单个 skill 的输出结构单测的核心目标是回答一个问题给定固定输入这个 skill 能否稳定产出符合要求的输出。对 code_review 这个 skill 来说单测就是准备几段已知问题的代码断言输出里是否包含问题清单、是否标注了行号、严重级别是否符合预期。具体执行时我会维护一个 golden set——一组精心挑选的测试用例每个用例都有人工标注的标准答案或关键断言。跑单测时把输入喂给 skill检查输出是否满足断言。这里要强调一点单测检查的是结构和关键内容不是逐字匹配。LLM 的输出天然有随机性要求它每次一字不差既不现实也没必要。断言设计得宽松一点只抓住必须有的内容就够。5.2 集成测试放进真实 agent 里看表现单测过了不代表真实场景里能用。因为单测是直达的——直接给 skill 喂输入跳过了模型判断该不该调用它这一步。真实场景里模型要先从用户的话里识别出意图再决定是否激活这个 skill这里就可能出岔子。集成测试就是把 skill 装进完整的 agent 链路里用接近真实的用户提问去测。重点观察两件事一是触发率用户提到相关需求时模型有没有正确激活这个技能二是端到端质量从用户提问到最终输出整条链路跑下来的结果是否令人满意。我见过太多 skill 单测全绿、一进 agent 就失灵的例子基本都是死在触发环节——description 写得不行模型根本想不起来用它。所以练好集成测试就是在练好 description 的翻译能力。5.3 回归测试改了 A 技能怎么知道没弄坏 B技能之间不是孤岛。改了 A 技能的 description可能让原本归 B 的场景流向了 A改了 B 技能的 instruction可能影响它在技能链中输出的格式。这种连锁破坏只有回归测试才能兜住。回归测试的做法不复杂把之前所有 skill 的 golden set 串起来每次有任何技能变更就全量跑一遍对比每个用例的结果是否还在可接受范围内。我用的是一个很笨但很有效的办法——每次迭代都记录基线输出把跑得不错的输出归档下一次跑的时候做对比看有没有出现明显的质量滑坡。这个流程坚持下来团队里就没人敢改完 skill 不打招呼就走因为周一的全量回归会把你所有偷懒暴露得干干净净。5.4 评测指标别只盯着成功率最后说评测指标。做 agent 的人很容易只盯一个数字任务成功率。但 skill 评测单一成功率远远不够。我自己会额外看三个指标token 消耗同一个任务优化后有没有更省、平均迭代轮次agent 多少次操作之内完成轮次越多说明 skill 指引越不清晰、人工修正率输出有几成需要人工改这是质量最真实的镜子。这四个指标放到一起看才能全面判断一个 skill 的健康度。成功率 100% 但人工修正率 60%说明 skill 只是看起来能跑实际上并没有真正理解任务成功率 80% 但 token 消耗比别人高一半说明 instruction 写得啰嗦还有压缩空间。指标齐全了迭代才有方向。6. 我在这套体系里踩过的坑和最终沉淀的设计准则6.1 坑一描述写得太泛模型什么都往这里塞我最早写一个数据分析技能时description 只有一句用于数据分析相关任务结果用户说帮我把这个 Excel 整理一下模型也把它激活了。整数据的、做可视化的、跑统计模型的全被一网打尽。这个技能实际上什么都没分析好。后来我把数据分析拆成数据清洗探索性分析统计建模三个技能各自的 description 都写清楚了自己的适用边界和不适用场景触发准确率立刻上了一个台阶。描述的具体程度直接决定路由质量这句话我后来写进了团队的 skill 编写规范。6.2 坑二规则堆砌把 skill 写成了法典还有一个反向的坑。有时为了把 skill 做专业我会忍不住往 instruction 里堆规则一条两条五六条写到后面 skill 的核心流程被淹没在大量不要这样必须那样的禁令里。模型的执行效果反而更差——它把精力花在遵守禁令上忘了自己最该做的是完成主任务。这个教训让我明白了一个道理规则是护栏不是剧本。护栏两三道就够多了反而妨碍执行。核心流程要清晰边界规则要精简这俩得分开写别搅在一起。6.3 坑三版本升级没有兼容策略另一次踩坑是升级了报告生成技能的输出格式第二天发现下游接它的周报推演技能全乱了——上游换了接口格式下游还在按旧格式解析。因为没有版本兼容机制一次升级引发了一连串连锁故障。所以我现在对 skill 的升级设了一条规矩破坏性变更必须和大版本号绑定并且要提前通知所有下游消费方。非破坏性的优化比如补充规则、优化措辞走小版本号改了输入输出格式、改了核心流程的必须按大版本走并附迁移说明。这条规矩看着简单能省下大量排障时间。6.4 我最终沉淀下来的五条设计准则踩了这些坑之后我把经验收敛成了五条准则每次做新 skill 之前都会过一遍单一职责一个 skill 只做一件事描述里说清边界宁可多拆几个也不要硬塞。流程与规则分离核心步骤用清晰的流程化语言写约束规则单独成段别混排。触发描述具体化description 必须包含什么说法该触发和什么情况不该触发。参数少而精参数数量控制在 3~5 个每个参数说明来源和类型不给模型增加抽取负担。测试先行每个 skill 必须配套三个测试用例以上才能进入生产环境。这五条不是理论推演出来的是从一个个翻车现场里爬出来的。你说它多高深真没有。但就是把每个 agent 项目做扎实的基本功。如果你也在做自己的 skill 库不妨拿这几条去对照一下手头的 skill再看一眼最近的 agent 输出质量是不是有明显改善。磨刀不误砍柴工把技能这块地基打稳agent 的上限才能真正被你拉起来。
