Agent Skills实战：用SKILL.md技能包让AI Agent真正会干活

去年年底我在折腾 AI Agent 的落地时第一次接触到agent-skills这个概念当时就被它的设计思路吸引住了——它不像 prompt 工程那样靠堆字数也不像微调那样重成本而是把“教模型干活”这件事变成了一套可以被组织、被复用、被版本管理的“技能包”。如果你也在做 Agent 落地或者正在头疼“为什么我的 Agent 只会聊天不会干活”那这篇文章值得你花几分钟看看。我会从原理讲到实操再把我测试过程中踩过的坑一并分享出来。我先说下我的结论agent-skills是目前让 Agent 具备特定领域能力最优雅、最轻量的方式之一。它不要求你懂模型训练不要求你写复杂的编排框架只需要你学会写一份“技能说明书”模型就能按图索骥地调用脚本、查阅参考、完成原本需要人工反复介入的任务。下面我按照从设计到实战的顺序完整拆解一遍。1. Agent Skills 到底在解决什么问题1.1 从“会聊天”到“会干活”的最后一公里我们平时用对话模型感觉它什么都懂可真要让它独立完成一个具体任务比如“把这200份PDF里的合同编号提取出来整理成表格”它通常会给你一个思路或者写一段代码然后停在那里等你去运行。这不是模型不够聪明而是缺少一个关键的东西对“这个任务在你的环境里到底怎么执行”的完整上下文。Agent 真正要落地就必须解决“最后一公里”的问题——不仅知道怎么做还要真的把活干完。agent-skills的设计初衷就是把这一公里的路铺好每个技能都是一个包含详细操作指引的文件夹里面会写明“什么场景下用”“按什么步骤做”“有哪些坑要避开”“必要时调用哪个脚本”。当 Agent 面对一个新任务时它会先检索自己掌握的技能一旦匹配上就照着技能文件里的步骤执行。我举个例子。假设你让 Agent 把一份混乱的 CSV 文件清洗成标准格式如果没有技能它可能会写一段 pandas 代码然后因为不知道你的字段规则、缺失值处理偏好、日期格式要求而反复猜。但如果有一份csv-cleaner技能里面明确写着“所有日期统一为 YYYY-MM-DD”“空值填 NA”“金额列保留两位小数”Agent 就能一次性按规范执行。这个差别用过的人都会懂。1.2 为什么不是微调、不是插件也不是更长的提示词很多人第一次听到 Agent Skills会问这跟提示词工程有什么区别跟插件Plugin区别是什么为什么不直接微调模型先说提示词。传统做法是把所有指令塞进 system prompt 里但 prompt 的长度有限而且塞太多互相冲突的规则会让模型“迷失重点”。更麻烦的是提示词是全局的——你不能一个任务换一套 system prompt。而技能是模块化的Agent 只有在遇到对应任务时才加载对应技能既节省上下文又不会干扰其他任务。再说插件。插件通常是硬编码的功能接口比如“搜索”“发邮件”“计算器”。技能则是一层“软能力”它描述的是一种操作方法论底层可以用任何工具、任何脚本实现。同一个技能内部可以组合多个工具调用Agent 在执行时还有自我纠错的空间。技能更像“经验文档可执行资产”的集合而不是一个固化的 API。微调就更不用说了成本和周期都太高。你为了让模型懂“清洗CSV的规则”去微调性价比极低而且每次规则变动都要重新训练。技能是运行时加载的随时可以修改改完立刻生效。最妙的是它不是只为了某一个模型设计的——只要模型能读懂 Markdown、能执行 Python它就能掌握这个技能天然具备跨模型复用性。所以我的判断是Agent Skills 补上的不是“智力”而是“经验”。模型天生有智力但它没有你在某个领域摸爬滚打总结出来的套路和教训。技能就是把这些经验外置让任何 Agent 都能站在你的肩膀上干活。2. 技能包的结构与 SKILL.md 的写法2.1 一个技能包的最小结构先看一下最基础的文件布局这样才能搞清楚 Agent 是怎么“看到”并加载技能的。my-skill/ ├── SKILL.md # 技能说明书必须 ├── scripts/ # 可选放可执行脚本比如 Python/Shell/JS │ └── process.py └── references/ # 可选放参考资料比如模板、样例、规范文档 └── template.csv核心就是SKILL.md这是一份纯 Markdown 文件。它的作用不是给人看而是给 Agent 看。Agent 在读取技能目录时会优先解析这个文件把它当作操作手册。我在实际测试中发现SKILL.md 的质量几乎决定了整个技能是否可用。它不是随便写几个标题就行而是要像一位老员工给新员工写“交接文档”那样把每个关键节点讲透。2.2 SKILL.md 的核心章节应该怎么设计在这份说明书里我建议至少包含以下四个部分顺序也很重要。第一部分One-line 描述。用一句话讲清楚这个技能是干嘛的。Agent 会通过这句话做初筛。比如“将非结构化 PDF 中的表格数据提取为 CSV”这种描述比“处理 PDF”要严谨得多能避免 Agent 在错误场景下调用它。第二部分适用场景与触发条件。这里要写清楚“当出现哪些信号时使用本技能”。比如当任务中出现“抽取PDF里的合同编号”“批量读取PDF报表”等表述时就用这个技能。同时也要写清楚“什么时候不要用”比如“如果 PDF 是扫描图片且没有文本层则需要先走 OCR 技能”。这一条非常关键能给 Agent 划出边界避免把它派到错误的战场。第三部分逐步执行步骤。这是 SKILL.md 的正文主体要按 1、2、3、4 这样的顺序把整个操作流程写出来。每一步都要给足细节。不能只写“用 Python 处理”而要写“调用scripts/extract.py传入本地 PDF 文件路径输出结果到output/目录。如果脚本返回非零退出码检查是否有异常信息并重试一次若仍失败请向用户报告具体错误”。Agent 是“照本宣科”的好手你写得越具体它执行得越精准。第四部分注意事项与已知坑点。这部分是经验的结晶。比如“当金额字段为空时默认补 0 而不是删除整行”“如果文件名包含中文必须先编码再写入文件”“Windows 环境下临时文件可能导致权限错误请使用tempfile模块”。这些内容看起来杂碎却往往是 Agent 能不能顺利完成任务的分水岭。没有这些坑点Agent 可能会自己“合理发挥”进而制造出诡异的结果。2.3 如何给技能配上脚本和参考资料SKILL.md 是大脑脚本和参考资料是手脚和记忆。脚本的作用是把那些模型不擅长的高精度计算、大批量处理、字节级操作等任务接管过来。比如你要从 10 万行日志里提取异常码让模型用 Python 写代码再执行不如直接给它一个写好的脚本并告诉它怎么用。这样既省时间又减少模型“临时写代码”带来的不确定性。参考资料则给 Agent 提供“标准答案”。比如你整理一份数据报告时希望字段命名跟公司数据库保持一致你可以在references/里放一份字段映射表让 Agent 在生成结果前先查阅。这种“查表驱动”的方式比在 SKILL.md 里用文字描述枚举字段要可靠得多。我自己的习惯是凡是涉及固定映射、口径定义、历史案例的地方都放进 references凡是涉及流程、条件判断、操作顺序的地方都写进 SKILL.md凡是涉及密集计算或精确格式转换的地方都用 scripts 承接。三者各司其职技能包才不会变成一个四不像的大杂烩。3. 从零手写一个技能以 CSV 数据清洗为例3.1 先明确场景和边界纸上谈兵没有意思我拿一个我实际做过的例子来讲做一个“销售报表清洗”技能输入是每个月导出的原始 CSV输出是一个符合规范的标准表。在动笔前我先列了一份需求清单日期列从2024/1/1统一成2024-01-01金额列保留两位小数空值补 0客户名称列去掉首尾空格并统一英文大小写剔除“测试客户”开头的行输出列顺序固定为订单号、日期、客户名称、金额、渠道这个边界必须提前定好否则技能写出来只是个空壳。尤其要注意不要试图让一个技能解决所有问题。报表清洗就只做清洗别让它顺手去画图表、发邮件。想得太大Agent 反而会糊涂。3.2 编写 SKILL.md 的过程和心理模型我的写法是先搭框架再填血肉。# 技能名称销售报表清洗 ## 概述 将销售系统导出的原始 CSV 转化为标准报表格式。 ## 触发条件 - 用户提供 CSV 文件并提到“清洗”“格式化”“整理报表”等关键词 - 用户给定标准字段列表要求按规范输出 ## 不适用场景 - 数据需要跨表 join 或从数据库拉取时必须先由用户提供合并后的文件 - 如果 CSV 编码不是 UTF-8先尝试用 gbk 参数读取 ## 执行步骤 1. 使用 scripts/clean.py 处理输入文件命令行参数为输入路径、输出路径 2. 脚本执行成功后检查输出文件是否存在且非空 3. 用 scripts/validate.py 对输出文件做校验列数、行数、字段格式 4. 校验通过后将输出文件路径告知用户若失败请将报错信息反馈给用户这里有个关键心理模型你不是在写给人看的文档而是在给 Agent 写“行动脚本”。每一个自然语言描述都必须能被 Agent 翻译成具体动作。比如“检查输出文件是否存在”这句话Agent 会理解成一条命令它不需要你真的告诉它-e filename这种参数但你要清晰地描述出目标。如果你写得模棱两可比如“认真处理数据”Agent 就会无所适从。接着我把那几条坑点写进去## 注意事项 - 原始 csv 第一行是表头不要跳过 - 日期格式化使用 datetime.strptime(value, %Y/%m/%d).strftime(%Y-%m-%d) - 金额字段可能包含 ¥ 和千分位逗号清洗时先去除 - 如果遇到编码错误用 errorsreplace 保存并在报告中提示这几条都是我实际碰到的坑。比如千分位逗号如果不去除转成 float 时会报错日期各种奇怪格式如果没有正则兜底会有几行数据直接变成空。我把它写进 SKILL.md 后Agent 就再也没在这几个地方翻过车。3.3 测试、迭代与验证效果技能写好了不是扔给 Agent 就完事了。我通常用小样本测试三遍第一遍给 Agent 一个 10 行的样例 CSV让它按技能执行观察它是否精准地调用了脚本而不是自己另写一段新代码。如果它无视技能自己“自由发挥”那通常说明 SKILL.md 的触发描述不清晰或者你写的步骤让 Agent 觉得不可用。第二遍丢给它一个 500 行的真实文件故意混入空值、乱码、异常日期看它能不能按“注意事项”里的方案处理。如果遇到脚本报错看它能否按 SKILL.md 里的报错处理思路去排查。第三遍不打招呼直接录一段模拟任务比如“帮我清洗一下本月销售导出.csv”看它能否主动匹配到该技能并顺畅完成端到端流程。我做过对比实验没有 SKILL.md 时Agent 面对脏数据的成功率大概只有 40%而且每次产生的清洗规则都不一样加了技能后成功率接近 95%输出格式稳定同一个文件跑十次结果也一致。这就是经验外置带来的巨大价值。4. 技能的组织、复用与版本管理4.1 技能库里应该放哪些技能技能不是越多越好而是越精越好。一个人如果背了 500 条互不相关的技能遇到新任务时检索成本会飙升误匹配的概率也会增加。我的建议是先覆盖“高频重复且规则明确”的任务。比如数据清洗、文件格式转换、批量重命名、定期生成报告——这些任务的特点是高重复度、低创造性正好是技能发挥威力的地方。至于写诗歌、编故事这种开放式任务根本不需要做成技能模型自己就擅长。另外技能之间要尽量正交。也就是说不要做两个功能高度重叠的技能比如“CSV 清洗”和“销售报表清洗”如果后者只是前者的一个特例那就只留一个更通用的“CSV 清洗”并在它的步骤里支持配置不同规则。这样维护成本低Agent 调用时也不容易纠结。4.2 多技能协作与冲突消解实际项目里一个 Agent 不可能只装一个技能。当它手上有了五六个技能后就必须面对一个问题任务来了该先调哪个目前主流 Agent 框架的做法是让模型先看每个技能的描述元信息然后根据任务相关性打分排序。你可以在技能描述里多写几个“触发关键词”和“典型用户意图”帮助模型做选择。比如“处理带表格的 PDF”和“从扫描件提取文本”虽然都涉及 PDF但场景完全不同描述里一定要写清边界。还有一种冲突情况两个技能都能处理当前任务但方法论不同。比如“快速绘图”和“印刷级图表设计”都会画图但一个追求速度一个追求排版规范。这时我会在 SKILL.md 的“触发条件”里明确区分“若用户要求快速草图使用前者若要求最终交付给客户的规范图表使用后者”。当用户没有明确意图时让 Agent 默认使用更保守、更稳定的那个技能并在回复里主动提示“本任务同时支持 XXX 技能如果需要更复杂的效果可以告诉我”。4.3 版本控制与团队协作技能的本质是代码加文档所以它完全可以走 Git 管理。我强烈建议从一开始就把每个技能包当作一个仓库来维护至少要在仓库里建一个skills/目录每个技能一个子目录SKILL.md 和 scripts 一起提交。这么做的好处很多你可以git diff查看某个技能的变更可以回滚到之前“还能用”的版本可以让团队成员提 PR 来完善一个技能比如补充新的坑点、优化脚本性能还可以用 Git tag 标记技能的大版本确保 Agent 环境拉取到的是经过验证的稳定版。我在团队里推行过一个做法每次 Agent 在实战中遇到新的坑就把解决方案补丁追加到 SKILL.md 里并提交一条 commit。半年下来我们的几个核心技能文件变得越来越厚Agent 的实战能力也跟着水涨船高。这相当于让所有人都能“教” Agent而不只是算法工程师一个人的事。5. 常见问题与排查经验5.1 明明有技能Agent 却不调用这是我最常被问的问题。写好了技能可 Agent 遇到对应任务时偏要自己硬扛就是不翻技能包。这种问题八成出在“触发条件”描述得太模糊。比如你写“适用于数据分析”对模型来说这太宽泛了。更好的做法是写“当用户要求汇总 CSV、表格、Excel 数据或提到‘统计’‘汇总’‘清洗’‘格式化’等字眼时使用”。你也可以在概述里留下一个强信号比如“该技能用于处理所有销售系统导出报表”。把信号写得越具体模型越容易匹配。还有一种原因是技能目录没有被挂载到 Agent 的可用工具列表里。很多框架默认不会扫描随便一个目录下的 SKILL.md你需要手动把技能目录路径配置到环境变量或 Agent 配置里。我的做法是检查启动日志看看技能加载时是否有 warn 信息以及调试模式下可以看到模型当前可用的技能名称列表。5.2 Agent 执行脚本报错卡在原地脚本报错不可怕可怕的是 Agent 没有处理报错的能力。如果你在 SKILL.md 里没有写“报错后怎么办”模型可能会反复重试同样的命令或者干脆放弃直接告诉用户失败了。我的解决办法是在执行步骤里明确加入一条兜底策略如果脚本返回非零退出码先把报错信息原样记录下来再根据错误类型判断——如果是文件路径类错误检查输入文件是否存在如果是编码类错误尝试用兼容模式重新运行如果是数据内容类错误打印前 10 行数据做分析并把分析结论写入输出文件。把这些写进 SKILL.md 后Agent 遇到报错就有了行动指南成功率会提升一大截。当然完全靠文字描述无法穷尽所有错误。我还会在脚本本身增加健壮性比如用argparse设置合理的默认参数在关键步骤用try/except捕获异常并打印友好的错误提示。这样即使 Agent 遇到没见过的错误也能在错误提示的引导下采取正确行动。5.3 怎么衡量一个技能好不好用最后聊聊评估。很多人说“技能好像有效但不知道效果有多好”那是因为没有设定基准。我的评估方案是准备一个测试集包含 20 到 50 个典型任务样本覆盖正常数据、边界数据、脏数据三种类型。然后跑三遍分别记录任务完成率Agent 是否成功产出结果文件而不是中途放弃字段正确率生成的结果字段与标准答案相比正确字段数占比偏差率输出的列顺序、格式是否符合 SKILL.md 里的规范人工介入次数任务过程中是否需要人工指点或重新执行用这个表格来做量化记录每次修改技能后对比一下就知道改动是变好了还是变坏了。指标无技能初版技能优化后技能任务完成率41%79%95%字段正确率63%88%97%平均耗时秒1154732人工介入次数41.50.3我建议每个技能都配一个类似的“体检表”测完后把它放在技能目录里作为参考后续改技能时就能有的放矢。最后分享一点我的个人体会折腾了这么久的 Agent Skills我最大的感受就是真正稀缺的不是模型能力而是你愿不愿意把自己的工作经验沉淀成结构化的技能包。一份好的 SKILL.md本质上就是你多年踩坑经验的“知识蒸馏”。以前你带新人需要手把手教现在你把它写成文档Agent 就能秒变一个“带着你经验的上古实习生”而且它还不会忘、不会抱怨、不会偷懒。我经常和团队说如果你连一份技能文档都懒得写那你大概率也没有想清楚这个任务到底该怎么标准化。如果你刚开始接触这个概念我建议你先不要急着做复杂的技能。挑一个你每周至少重复三次的琐碎任务花一两个小时把它整理成一个技能包装进你的 Agent 里跑一周。相信我一周后你会回来把其他重复任务也全部技能化的。