1. 从一次重复调教 AI 说起为什么需要技能沉淀先说个真实经历。去年我做运营数据周报每周一都要让 AI 按固定口径分析销售表格再把结果改写成老板能看的结论。最开始我把那套规则直接塞进对话里每次都要重新粘贴一遍AI 还经常理解得跑偏后来我把规则写进了系统提示词算是稳定了一阵子但换个场景、换个工具又得重新来一遍最崩溃的是某个参数口径改了一次所有地方都跟着改漏一处就出错。被这件事反复折磨之后我才意识到问题不在提示词写得不好而在于我根本没有一套可以把复杂能力打包、复用、迭代的载体。这时候我接触到了 agent-skills 这个概念——把过去散落在对话里、系统提示词里、五花八门的工具脚本里的经验沉淀成结构化的技能文件让 Agent 在需要的时候自己调用。这个思路直接解决了我上面说的三个痛点不用每次重复调教、不用在一个巨型提示词里堆砌所有规则、改一处只需改对应的技能文件。这篇文章就是围绕 agent-skills 写的一份实战笔记。我默认你已经在做 Agent 相关的东西可能是用 Claude、DeepSeek 这类模型写自动化脚本也可能在用 LangChain、CrewAI 搭多智能体应用或者只是在用各类带 Agent 功能的效率工具。本文的核心话题是怎么把让模型稳定干活的能力抽象成可复用、可测试、可版本化的技能以及这一套方法在不同框架下怎么落地。需要先说清楚一个边界技能Skill不等于工具Tool也不等于工作流Workflow。工具是确定性的代码函数例如调用这个 API 拿天气数据工作流是固定顺序的步骤编排例如先抓数据、再清洗、再入库。而技能是一段带上下文、带示例、带约束的指令包它依赖模型的推理能力去理解什么时候该用、怎么用、用到什么程度。三者的关系有点像工具是肌肉工作流是骨架技能才是大脑里的反应模式——它知道用哪些肌肉、按什么节奏做动作。这篇文章适合两类人。第一类是正在做 AI 自动化但发现自己换了模型、换了项目就要重写提示词的人你需要一套技能化的沉淀方法第二类是团队里已经有多人各自维护 Agent 配置想把这些散落的经验统一管理、统一迭代的人你需要一套技能库的组织规范。看完之后你至少能动手建出第一个技能文件并知道用什么标准去衡量这个技能写得好不好。2. 动手前先想清楚我的 Agent 到底需要哪些技能很多人第一次接触 agent-skills第一反应就是那我把我所有的工作流都写成技能文件。千万别这么干。技能不是越丰富越好而是越精准越好。技能库如果塞满了低质量技能Agent 在调用时反而会因为选择过多而选错或者在一个技能里硬套另一种任务的方法。2.1 从高频重复、且规则相对稳定的任务开始我建议你只做一件事翻自己过去两周和 AI 的聊天记录把出现过三次以上的任务类型列出来。注意是任务类型而不是具体任务。比如帮我把这段会议纪要整理成 To-do List和帮我把这段采访记录整理成行动清单本质上是同一个技能——从非结构化文本中提取行动项。再比如帮我看看这个数据表里哪些渠道的收入异常和分析一下这周用户流失的原因底层都是给一个数据源和业务背景输出结构化分析报告。这类任务通常有几个共同点第一你已经摸清了稳定做法不需要每次从头试第二模型容易在某个环节犯错你已经在提示词里补过多次说明第三输出格式是你或团队反复调整过、已经定型的。这三个信号同时出现就是技能化最合适的机会。我自己还有个筛选标准这个任务需要 500 字以上才能把规则说清楚吗如果 100 字的提示词就能搞定那它还不值得写成技能如果超过 1000 字还在不断增加内容那说明这个技能应该继续拆解。技能是给 Agent 当参考手册用的不是让 Agent 背下来的命令行它应该有合适的厚度。2.2 用场景边界反推技能的分割粒度技能设计最容易犯的错是把粒度搞错了。我见过有人写一个叫数据处理的技能里面既包含 CSV 清洗、又包含 JSON 转换、还包含数据可视化建议一个文件写了两千字。这种技能看起来全能实际调用效果很差——因为模型在遇到具体输入时不知道应该触发哪一段规则经常把清洗规则套到可视化环节上。正确的做法是按输入的类型和输出目标来划分边界。打个比方就像你把菜刀和削皮刀分开挂不是因为它们都叫刀所以要放一起而是因为使用场景不同。如果两个任务使用同一份输入、但输出目标完全不同它们是两个技能如果两个任务输出目标相同、但输入格式完全不同它们也是两个技能。以一个具体例子来讲把销售表格转成图表描述和把销售表格转成业务建议输入一样输出不同所以是两套技能处理 CSV 报表和处理 PDF 合同文本虽然都叫提取关键信息但方法差异太大也应该拆开。命名风格我推荐用动词对象的结构比如制定周报分析框架提取表格关键字段审查文档逻辑一致性。命名的时候把 description 字段写得像搜索引擎的摘要一样说清楚这个技能适用于什么输入、产出什么、以及最重要的——什么情况不该用它。2.3 技能目录的结构规划我建议把技能库按领域和通用能力两层来组织。领域层对应你的业务场景例如销售分析内容创作客户支持通用能力层是跨场景的例如信息摘要结构化改写质量审查。这样做的好处是通用能力技能可以被领域技能引用形成组合而不是每个领域都各自写一份摘要方法改起来重复劳动。这一步想明白之后就可以开始建第一个技能文件了。不要追求一上来就完整覆盖所有场景先把最痛的那个高频任务做透你会在使用过程中自然摸索出更合适的粒度。3. 第一版 Skill 从零到跑通一个完整的技能文件模板现在进入实操环节。目前主流的 agent-skills 实现方式基本都采用一个技能一个目录目录里有 SKILL.md 主文件可选附带参考资料、示例、脚本的结构。无论你用的是 Claude 的 Agent Skills、CrewAI 的 Skill还是自己写的加载器这套结构的底层逻辑是通用的用文本描述能力用文件组织依赖用目录结构支持扩展。3.1 最小组件SKILL.md 的必备字段一个最小可用的技能文件至少要包含以下四块内容字段作用说明name技能的唯一标识简短用连字符连接例如weekly-report-analyzerdescription技能触发条件说明明确什么任务、什么输入下才应该调用这个技能instructions核心操作步骤告诉模型按什么逻辑执行步骤要有分支判断examples输入输出示例展示典型场景下的期望行为description 是最容易被忽略、但实际影响最大的字段。因为在大部分 Agent 架构里模型是通过 description 来决定是否调用技能的而不是把 SKILL.md 全文都读一遍。如果 description 写得太泛比如用于处理周报那模型遇到任何跟周报沾边的任务都可能调用它包括帮我把周报发送到群里这种根本不需要分析能力的事。更好的写法是带上输入条件和输出目标比如输入为销售/运营数据表格输出为面向管理者的结构化周报分析不适合用于原始数据清洗。instructions 部分是技能的核心要写的是执行逻辑不是流程口号。我给下面示例里用的步骤式分支式混合写法是经过大量测试相对稳妥的格式主流程用步骤编号关键判断点用如果...则...分支避免模型自作主张跳步。3.2 一个能直接抄的示例销售周报分析技能直接上代码块这个是我实际在用的简化版本你可以体验一下整体结构--- name: sales-weekly-analysis description: 适用于输入销售明细表或渠道汇总数据输出包含核心结论、异常点、 下步建议的周报分析结果。不适合处理非数据类文本也不适合做预测建模。 --- # 销售周报分析 ## 适用场景 - 输入销售明细 CSV、渠道汇总表、GMV 走势数据 - 任务目标识别本周变化、定位原因、给出下一步动作建议 ## 执行步骤 1. 先读数据确认字段含义和统计口径。 - 如果字段中有渠道、订单量、GMV按渠道维度做汇总。 - 如果字段中只有订单量、GMV没有渠道按时间维度做趋势分析。 - 如果数据量小于 5 行不要强行做趋势分析直接列出明细并标注样本不足。 2. 和上周做环比。 - 先算出每个渠道 GMV 的环比变化率标注出增长/下降超过 15% 的项。 - 增长率计算时用 (本周值 - 上周值) / 上周值保留一位小数。 3. 对超过阈值的变化做原因排查 - 优先在数据中找支撑性证据例如某一渠道订单量剧增看是否对应明显促销记录。 - 找不到明确证据时输出原因待确认禁止编造业务归因。 4. 按以下结构输出结论 - 本周概述2-3 句话概括整体表现。 - 核心数据用表格列出渠道、GMV、环比、变化率。 - 异常点列出超过阈值的变化项以及推测原因。 - 下周建议最多 3 条必须基于前面分析禁止泛泛而谈。 ## 注意事项 - 不要使用 2020 年之前的默认历史数据做基准除非用户明确指定。 - 输出中使用用户原始表格里的货币单位不自行转换。 - 当某渠道本周无数据时写无数据而不是 0避免误导环比计算。 ## 示例 输入渠道汇总表本周 GMV: 淘宝 120 万京东 80 万上周: 淘宝 100 万京东 95 万 输出 本周概述整体 GMV 环比增长 5.26%主要受淘宝渠道拉动。 核心数据 | 渠道 | 本周 GMV | 上周 GMV | 环比 | |------|---------|---------|------| | 淘宝 | 120 万 | 100 万 | 20% | | 京东 | 80 万 | 95 万 | -15.8% | 异常点京东渠道下滑 15.8%已超过 15% 阈值数据中未见促销或大促记录原因待确认。 下周建议1. 排查京东渠道流量来源变化2. 关注淘宝增长是否可持续3. 对下滑渠道做用户回访。你可以看到这套结构的核心不是教模型写周报而是限制模型在关键环节不要乱猜。比如第 3 步里我明确写了禁止编造业务归因第 4 步规定输出格式这两个约束直接避免了 Agent 最常见的幻觉问题。3.3 为什么使用 Markdown而不是代码脚本或 JSON 配置很多人会问技能为什么要用 Markdown 文件直接写 Python 脚本调用不好吗这个问题我当时也想了一阵。答案是技能的消费者是模型而不是程序。模型是文本推理器自然语言对它来说是最低成本的可执行代码。一个 100 行的 Markdown 文件模型读一遍就能理解全部约束如果用代码脚本每个脚本还需要额外配注解、参数说明、异常处理最后效果未必比自然语言稳定但维护成本高得多。退一步说Markdown 文件本身就是文本天然支持 Git diff你改了一个字段、加了一句注意事项在版本历史里都能看得到。这在团队协作场景里太重要了因为技能是会进化的你总想知道上一次还能用这次怎么突然不行了而答案往往就藏在 diff 里。你可以在技能目录里额外放脚本文件或数据文件只要在 SKILL.md 里说明它们的用途和使用方式。但主文件一定得是纯文本、模型可直接阅读的。这个原则要坚持住。4. 把技能做厚的关键细节指令、示例和检查清单怎么写基础版技能能跑通但距离稳定往往还差得远。我发现大多数人的技能文件写出来之后第一次实测的错误率还是很高的原因基本都出在三个地方指令太僵硬、示例太少、缺少输出前的自查机制。这一节我把这三个坑逐个说透。4.1 指令要面向推理而不是面向流程先说指令的写法。新手最常犯的错误是写手把手流水账第一步打开文件。第二步读取数据。第三步计算增长率。第四步输出报告。这种写法有两个问题一是模型每一步都缺少判断依据遇到文件打不开或者数据缺失时就卡住了二是太过线性的步骤容不下真实场景里的分支情况。更好的写法是给出目标、给出约束、给出分支判断条件。你在第 3 节的示例里已经看到我在每个步骤里都埋了 if-then 分支。这些分支不是凭想象写的而是来自我对真实数据的观察。比如电商周报里经常出现某渠道这周没数据如果不提前在技能里说明这个情况应该写成无数据还是0模型每次会随机选择一个结果周环比计算就跟着错。另外一个小技巧在步骤后面加一行为什么这么做用一两句话解释这个步骤的目的。模型的指令遵循能力很强当它理解了目的之后遇到指令没有覆盖到的边界情况会按照目的去合理推断而不是死板地按字面执行。我在调研技能里写过输出分类标签时不要给置信度过低的预测目的是防止下游误判宁可漏报不要误报模型在遇到模糊输入时就会主动选择更稳妥的分类方式效果非常明显。4.2 示例的三层作用格式、语气、边界示例在技能文件里的重要性怎么强调都不过分。很多文档只写指令不写示例模型的输出会变得五花八门。我给技能写示例时会刻意放三类内容第一类是标准成功案例这告诉模型输出长什么样。第二类是带边界情况的案例比如输入数据量过小或缺少关键字段时应该如何处理这类示例对模型的引导作用比任何指令都强。第三类是不该怎么做的反例我会把常见错误写法直接放在示例里并标注这是错误示范禁止这样输出。说个我自己的教训。有一版技能里我只放了一个成功示例模型在遇到另一种渠道名格式时就固执地套用了示例里的种子风格甚至把京东写成了淘宝。后来我加了第二个示例里面特意用了个冷门渠道名并注明渠道名应以输入数据为准优先级最高这个问题就再没出现过。你仔细体会一下模型不是在理解规则而是在匹配模式。示例就是模式的锚点多点几个锚模型才能找到正确的位置。4.3 检查清单给 Agent 装上事中刹车我在技能里必加的一段内容是输出前自查清单放在执行步骤的最后。这段不是给用户看的是给模型自己在生成最终回答前逐项核对用的。我常用的清单项有是否使用了与用户输入一致的单位是否所有关键字段都有数据支撑是否存在超过阈值的异常点没被解释输出结构是否严格按照目标格式本质上检查清单相当于把事后纠错提前到了事中巡检。模型是生成式模型它输出完一段话之后往往不会主动回顾自己的逻辑链有没有漏洞。你在技能里写按以下清单重新检查你即将输出的内容等于强制要求它把自己的回答当作输入再读一遍这个动作能挡掉相当一部分低级错误。自检清单怎么设计才有效我的经验是不要超过 5 条每条都要可以机械判断例如环比公式是否使用 (本周-上周)/上周而不是抽象地问数据是否准确。数据是否准确这种条目模型无法自查问了等于没问因为它并不知道正确答案而是否有任何增长超过 15% 的渠道没写进异常点是可以数出来的模型能执行。4.4 信息过载时怎么办把技能拆成多文件最后说一个规模问题。技能文件如果超过 200 行模型到后面会开始丢失前面指令的权重信息尤其是注意事项里的约束和正文步骤里的指令冲突时模型通常会按前面的步骤执行把注意事项抛到脑后。遇到这种情况我建议你做两件事第一把技能拆成主文件参考文件。SKILL.md 只保留核心执行逻辑和触发条件把领域知识、详细背景、额外案例放到同目录下的 references 文件里在主文件的合适位置用遇到 X 情况时先阅读 references/xxx.md来引用。模型会按需取用而不是一上来加载全部内容。第二把步骤当作硬约束、注意事项当作软约束来区分写法。步骤部分用最明确的祈使句注意事项部分则说明条件场景。模型对必须禁止这类词的权重响应很高用这些词时要谨慎只有在真正不可违背的规则上才用。留一些缓冲地带给模型发挥反而能提升整体可控性。5. 实测和调优验证技能效果的完整链路技能文件写完只是起点真正让它稳定的关键在于测试。很多人在这一步偷懒直接把技能丢进生产环境等出了问题再改。这样也不是不行但你会发现每次改动都不知道到底改好了没有因为缺少一个可对照的基线。我后来养成了一个习惯每个技能都配一个小型测试集每轮修改都跑一遍测试用输出结果的差异来指导下一步优化。5.1 离线测试先跑通主流程离线测试指的就是不接真实业务数据用你自己的测试输入来验证技能。我建议每个技能目录下留一个samples/文件夹放 3-5 组典型输入。这里有个原则测试样本要包含正常样本、边界样本和错误样本而不能只放你最希望遇到的那种正常情况。跑测试的过程很简单把技能文件加载进 Agent 环境用样本输入触发调用然后把输出保存下来。目标是建立一套基线输出。比如周报分析技能第一版跑出来的结果可能把环比算错、漏掉某个异常渠道、格式也不对这些就是后续迭代要解决的问题清单。第一次基线难看没关系关键是把它保存下来这样你才能看到每一次改动到底带来的是变好还是变坏。你还需要一个手段来快速加载技能进不同环境。我目前用的是把技能目录放到 Agent 的配置目录下例如 Claude 生态里常见的.claude/skills/或者自己写一个简单的加载函数把 SKILL.md 读进系统提示词。开源项目里普遍支持这种目录约定用起来成本很低。5.2 边界测试故意喂不完整的数据边界测试是最能暴露技能短板的一步。我踩过的坑基本都集中在边界情况里。举几个真实的例子渠道数据为空时模型把 0 当作数值参与环比导致出现 -100% 这类荒谬结论输入数据是英文时模型擅自把单位从万美元改成了美元而没有按技能里单位与用户保持一致的约束执行数据量只有 3 行时模型仍然强行生成了 5 个渠道的对比表编出了一堆不存在的渠道。遇到这些问题不要第一时间想着再加一条注意事项就能解决。你需要分析这个错误是说明性问题还是结构性缺陷。如果属于模型不知道该怎么办更好那就加分支指令如果属于模型在多种规则之间产生了冲突那你得调整优先级明确哪条规则优先于哪条。我测试的时候特别喜欢用删字段的办法把样本里的某个关键字段删掉看看模型会不会报告数据缺失而不是硬着头皮改出一个值。一个好的技能在这个场景下应当是表现出知道自己不知道——这是技能稳定性的一个重要指标。5.3 回归对比与版本迭代技能修改到最后最怕的是修好了边界情况却把正常情况弄坏了。这就是回归测试的价值。每次改完技能文件我把 5 组样本全部重跑一遍然后把新的输出和基线输出做对比。如果某组正常样本的输出出现了不合理的偏差那就说明刚才的修改副作用太强需要拆掉或者调整。版本管理建议直接走 Git。技能的变更日志不必像软件工程那样讲究但最好在技能的 frontmatter 里维护一个简单的version字段和updated日期。这样当你发现某个技能行为突变时能立刻知道是不是因为自己改了文件导致的。迭代的节奏上我一般遵循一次改一个变量的原则。有些时候你觉得技能效果不好可能同时存在指令不清晰、示例不足、约束冲突三个问题但你一次全改完根本不知道是哪条改动起的作用。忍住一次只改一个点跑一遍测试记录结果再动下一个点。这个方法笨但可靠。5.4 实测中常见的三个技能失效场景最后分享几个我实际遇到过的技能失效案例你可以把这些当成检查方向遇到问题先对照一遍症状根因解决方式模型在该用技能时没触发description 写得和用户问法差异太大把 description 扩写包含更多用户可能的表述方式并加入否定条件触发了但执行顺序混乱步骤与步骤之间缺少明确衔接或分支条件过多精简主流程把分支逻辑收敛成按条件选择不同后续步骤输出了格式对、结论荒谬技能里缺少禁止编造数据的硬性约束在注意事项中增加数据来源限定并添加输出前自查清单第二个场景我想多说一句。模型是概率生成当技能里出现超过 10 个并列的分支时它经常会在分支判断上产生混淆选了一个不是最优的路线。碰到这种情况我通常会把多个分支统合成一个先判断、再选择的步骤而不是把分支写成一串 if 条件链。人看着很清晰的结构模型读起来可能已经绕晕了。6. 技能库的进阶玩法跨项目复用、团队共享与组合技能一旦积累到 10 个以上就会进到一个新的阶段它不再只是你个人的小工具集而是可以成为团队协作的公共资产。这个阶段需要考虑的问题不再是某个技能怎么写而是整个技能库怎么组织、怎么共享、怎么演化。6.1 把技能库变成一个可审查的仓库我强烈建议把技能库单独放在一个 Git 仓库里目录结构大致如下skills/ analysis/ sales-weekly/ SKILL.md samples/ references/ user-retention-analysis/ SKILL.md content/ meeting-note-to-action/ SKILL.md common/ structured-summary/ SKILL.md quality-review/ SKILL.md这个结构的好处是每个技能自包含不依赖全局环境目录层级表达了领域归属让新成员能快速找到相关技能Git 历史记录了每次改动的来龙去脉可以做 Code Review 式的技能审查。在团队场景里我要求每个人提交新技能或修改已有技能时必须附带两条说明改动解决了什么真实问题、影响到了哪些旧输出。这两条不可妥协。共享方式上不同的 Agent 工具生态有不同的加载约定但本质都是把技能目录映射到某个路径。你可以直接把这个仓库 clone 到每个人的本地目录也可以写一个简单的同步脚本从仓库拉取最新文件复制到对应位置。如果有 CI 环境再加一条自动化检查校验每个技能的 frontmatter 必需字段是否齐全、示例文件是否存在、描述是否超过 20 字。这种检查的价值在于它能在技能还没进入 Agent 环境前就拦截掉低质量提交。6.2 技能的组合让多个技能协作而不是堆叠技能之间是可以组合的。比如我有一套内容生产流程用了三个技能的组合信息提取把原始材料整理成结构化摘要内容生成把摘要扩展成初稿质量审查对初稿做逻辑和格式校验。每个技能本身都很轻组合起来却能完成一个完整的复杂任务。组合的方式并不需要专门写一个编排引擎大部分情况下在技能的 instructions 里引用其他技能名字即可例如在内容生成技能里写一句输入材料已经由信息提取技能处理为结构化摘要直接基于摘要开始扩展。模型在上下文中会保留前面技能处理的输出自然就知道该怎么衔接。这种设计也让技能之间保持了解耦你想替换信息提取的实现方式根本不会影响内容生成的技能。不过组合技能时我有一条铁律每个技能只对自己的输入输出负责不要在技能 A 里假设技能 B 一定做了什么事情。比如内容生成技能仍然需要在自己的 instructions 里定义如果输入不是结构化摘要应先将输入整理成结构化摘要再执行而不是直接摆烂说没有摘要我生成不了。技能之间的依赖越弱整个技能库越稳定。6.3 技能库演化过程中的两个常见问题技能库规模上来之后还有两个问题值得提醒。第一个是技能漂移你不断给某个技能打补丁、加边界规则加的多了之后模型对技能中心目标的响应反而会减弱因为注意力被大量边缘情况稀释了。一个技能如果不定期减肥很快会变成一个臃肿而混乱的规则堆。我给自己定的规矩是技能文件超过 150 行就要审视是否需要拆分超过 200 行直接拆分不做犹豫。第二个问题是技能冲突两个技能的 description 覆盖了高度相似的任务模型在触发时可能随机选择一个导致输出风格和逻辑对不上。避免的办法是每新增一个技能都要在技能库里搜索一下已有技能的 description 是否有重叠。如果重叠度很高但你又确实需要区分那就必须在它们的 description 里明确写出彼此的适用边界例如一个写适合处理月度汇总数据另一个写适合处理每日明细数据。这是把话说死的做法但很有效。技能这个东西我从开始摸索到现在最大的体会是它比工具灵活、比工作流通用、比提示词可维护。但它的难点也在度上——写得太细则僵化写得太粗就没约束技能太多则难选技能太少则不够用。好在他是一个可以渐进演进的系统你不用一开始就搭出一个完美的框架先从一个最痛的任务开始把第一个技能用好再慢慢扩展。所有的调优经验、踩坑记录都会沉淀到技能本身这也算是另一种意义上的复利。