做了快两年的智能体落地项目我最大的感触是绝大多数团队的问题根本不是“模型不够聪明”而是“模型不知道怎么干活”。你说他能写代码、能分析数据、能总结文档可真让他按你们团队的规范走一套流程十次有八次会跑偏。后来我开始认真研究 agent-skills 这个概念就是给智能体建一套标准化的“技能库”情况才彻底改观。agent-skills 简单说就是把那些需要稳定输出、重复执行的复杂任务沉淀成一个个可复用、可测试、可版本管理的“技能文件”。它不是提示词也不是插件而是介于两者之间的一套操作标准告诉智能体什么场景下启用、按什么步骤执行、输出成什么格式、用哪些检查项来验收。这套东西一旦铺开智能体就从“会聊天”变成了“会干活”。这篇文章我会把这大半年的实践经验完整拆一遍技能是什么、技能库怎么设计、五个高频场景怎么写、从零搭一个技能库需要哪几步、踩过的坑有哪些以及怎么把个人技能资产变成团队资产。不同基础的人都能找到自己能用的那部分。1. Agent技能到底是什么从“会聊天”到“会干活”1.1 模型缺的不是知识是稳定执行能力先说一个很扎心的现实大模型的知识储备和推理能力已经很强了但它天然不擅长“稳定地按流程做事”。你让同一个模型分三次处理同一份周报可能第一次输出表格、第二次写成纯文本、第三次干脆漏了一个章节。问题不在于模型笨而在于它每次都在现场“即兴发挥”。技能Skill就是冲着这个痛点来的。一个技能本质上是一套标准作业程序SOP它告诉模型你现在的角色是什么、你面对什么输入、你必须按照哪几个步骤走、每一步的输出长什么样、最后用什么标准自检。这样模型就不再靠猜而是靠“查手册”。你可以把技能理解成给新员工发的一本岗位培训手册。手册里写清楚了流程、规范、验收标准新员工照着做虽然不能保证每次都惊艳但能保证每次都及格。及格对于生产力工具来说比偶尔惊艳重要得多。1.2 Agent Skills与RAG、提示词的本质区别很多人刚接触这个概念时会混淆三个东西RAG检索增强生成、系统提示词、Agent Skills。我做一个比较直白的区分RAG解决的是“知识缺失”问题。比如模型不知道你们公司内部的报销流程你通过检索把相关文档塞给它。它知道得更多了但仍然不知道“该用什么步骤把这套流程走完”。系统提示词解决的是“身份与方向”问题。它定义了模型整体的行为基调类似给员工讲企业文化。但提示词不能随任务切换塞太多还会互相干扰。Agent Skills解决的是“任务级执行”问题。它把某个具体任务的操作流程、参数规则、输出格式、验收标准全部封装起来模型在遇到匹配场景时才按需加载。RAG和提示词是“背景知识”技能是“行为规范”。背景知识告诉模型“世界是怎样的”行为规范告诉模型“活儿该怎么干”。这也是为什么技能文件通常叫 SKILL.md而不是 knowledge.md。它关注动作不关注百科。1.3 技能文件为什么比普通文档更有效我自己最早也犯过这个错把技能文件写成了操作指南一页纸全是“你应该做到专业、准确、全面”。结果模型读完了行为一点没变。后来我才意识到技能文件的核心在于三个字可执行。什么叫可执行第一触发条件要明确模型读到任务描述时能准确判断“该不该启用这个技能”第二步骤要是线性的一步做完再做下一步每一步都有明确的输入输出第三要有验收标准技能执行完怎么算好、怎么算坏模型自己能自查。这就是 SKILL.md 和普通文档的分水岭。普通文档是给人看的讲究信息完整技能文件是给模型执行的讲究动作明确。我建议所有写技能的人先记住一句话你写的不是一篇文档而是一个程序的控制流。你的“代码”是自然语言但逻辑必须是程序级的。2. 技能库的结构设计先搭框架再写内容2.1 目录分组按任务域划分而不是堆文件技能一多最尴尬的问题就是找不到、理不清。一开始我把所有 SKILL.md 都丢在一个 flat 目录里二三十个文件之后就已经分不清谁是谁了。后来我参考代码仓库的做法改成按任务域做二级分组结构大概是skills/ ├── engineering/ │ ├── code_review/ │ │ ├── SKILL.md │ │ ├── examples/ │ │ └── tests/ │ ├── refactor/ │ └── debug/ ├── data_analysis/ │ ├── weekly_report/ │ └── anomaly_detection/ ├── writing/ │ ├── blog_post/ │ └── meeting_notes/ └── operations/ ├── incident_triage/ └── log_analysis/每个分组目录下加一个 README.md写清楚这个分类下有哪些技能、各自解决什么问题、技能之间的边界在哪里。这样既方便人浏览变量模型在模糊匹配时也能通过目录路径获得额外的语义线索。分组的原则不要按“模型能力”分而要按“业务任务域”分。因为技能是给任务用的不是给模型用的。你面对的现实是写代码和修bug可能都属于开发域但它们的流程、检查项完全不同必须拆成两个独立技能。2.2 SKILL.md 的标准写法字段定义与意图经过反复调试我总结了一套比较稳定的 SKILL.md 结构。它不需要花哨但每个字段都有明确作用谁都不要删--- name: weekly_report description: 根据原始销售/运营数据生成结构化周报。当用户提到周报双周报本周数据汇总时使用。 ---YAML front matter 里最重要的就是 description。很多模型是通过语义匹配来唤起技能的description 写得好不好直接决定它该触发时能不能触发。我建议 description 里至少包含三个部分这个技能做什么、典型的触发说法有哪些、在什么情况下不要用。正文部分我推荐这样的顺序When to Use触发条件说明和 description 呼应Inputs Required需要哪些输入参数或文件Steps线性步骤一条一条列清楚Output Format输出结构、字段、模板Quality Checklist执行完要求模型自查的验收项写正文最大的陷阱是“写了知识没写动作”。比如你写“分析数据时要注意数据质量”这就是典型的废话你应该写“如果发现空值比例超过10%先报告异常再继续分析不要在输出中静默处理空值”。动作越具体执行越稳定。2.3 技能粒度先做窄技能别憋大招新手写技能最容易犯的毛病是想一口气解决整个工作流。比如“数据分析技能”听起来很大但真写起来会发现清洗数据是一套动作、做趋势分析又是一套动作、输出图表是第三套动作混在一个技能里只会让每一步都不够精细。我的经验是一个技能只解决一个主任务覆盖范围宁窄勿宽。与其做一个“全能数据分析”技能不如拆成 data_clean、trend_analysis、report_chart 三个窄技能。窄技能的好处有三个容易写清楚步骤、容易测试、容易排查问题。而且模型按需加载时窄技能更精准不会把不相干的规则一起加载进来干扰判断。命名也有讲究。我推荐用“动作对象”的格式比如 review_pull_request、parse_invoice_pdf、summarize_meeting_notes。这种命名有两个作用对模型来说动作和对象都是高信号词汇触发匹配更准确对人来说技能库一眼看过去就能知道每个文件的职责不会出现“看名字想不起来是干嘛的”的情况。3. 五个高频场景下的技能实战拆解3.1 工程类代码审查技能是怎么设计的代码审查是我用技能库落地最成功的场景之一。以前让模型帮忙看代码它经常给出“这个函数写得很清晰”这种毫无营养的评论或者一次性输出几十条无关痛痒的建议。后来我写了一个 code_review 技能效果立刻不一样了。这个技能的核心步骤是这样设计的先读取目标 PR 的完整 diff明确变更范围按检查清单逐项审查逻辑正确性、边界条件、错误处理、性能隐患、安全风险、代码规范所有问题按严重级别分级阻断性问题、建议改进、可选优化输出结构化报告按文件分节标明问题行号、问题描述、修改建议。关键点是“按清单逐项审查”。模型在自由发挥时容易遗漏维度但有了清单它会像体检一样一项一项过。我还特意在技能里加了一条规则如果没有发现阻断性问题必须明确写“未发现阻断性问题”而不是含糊地说“整体不错”。这能省掉大量和业务方扯皮的时间。3.2 数据类把指标口径写进技能就赢了数据分析类的技能最有价值的部分不是“怎么做分析”而是“口径固定”。同一个“销售额”不同人可能定义不一样是按订单支付时间算还是按创建时间算含不含退款含不含测试订单模型不知道这些细节就会每次给出不同的答案然后被业务方质疑。所以我写数据分析技能时第一步永远是“明确指标口径”把这些规则直接写死在步骤里。以销售周报为例销售额 当周支付成功且未退款的订单金额剔除测试订单订单量 当周支付成功的订单数量不含退款订单退款率 当周退款订单数 / 当周支付成功订单数。这类技能的核心价值不是让模型“生成代码画图表”而是让它“在固定的口径下生成代码画图表”。一旦口径写进技能输出的结果就有了可复现性。业务方看到周报数字不再变来变去信任度立刻上来。另外要强调一个细节数据分析技能必须要求模型先展示数据处理过程再展示结果。比如“你使用了什么清洗逻辑、去掉了多少异常记录、最后的统计口径是什么”整个过程可审计才不会出现模型自己编数据的情况。3.3 内容类批量生产内容的关键是质量闸门内容团队用技能做初稿最怕的不是写得差而是写得太“模型腔”。我用写作类技能的经验是与其在“文笔”上写一堆抽象要求不如设计一个残酷的检查清单把质量把控变成硬性的闸门。比如我团队写行业晨报技能步骤是这样的收集当日新闻源按主题去重每条新闻提炼核心信息主体、事件、影响、时间初稿每则简讯控制在150字以内必须有明确的数据或事实支撑自检清单是否存在没有来源的断言是否出现“据悉”“据悉”这类空话信息是否有明确时态是否有人名或机构名拼写错误全部通过后才能输出最终稿。这个流程的重点是第四步的自检清单。模型写内容时你没法实时干预但你可以通过强制自检环节让它自己先把低质内容杀掉一遍。实测下来加了质量闸门之后编辑需要返工的内容量减少了大半。还有一个独家心得内容类技能最好在步骤里加一条“如果你觉得内容无法达到清单标准直接告诉用户你无法完成并说明缺了什么信息”。这比让模型硬着头皮编一篇假大空的稿子强一万倍。3.4 运维类排障技能要连“处置动作”一起写运维场景下模型最大的价值不是诊断而是“按处置手册执行恢复动作”。很多人写排障技能只写判断逻辑不写操作动作结果模型诊断得头头是道却不会修这是个大坑。我的 incident_triage 技能是这样组织的输入告警标题、日志片段、系统拓扑信息第一步按错误码和日志关键字把问题映射到已知类别比如数据库连接池耗尽、磁盘占用超阈值、缓存穿透第二步针对每个类别读取对应的处置预案第三步执行最低风险的恢复动作如重启单节点、调整连接池上限、清理旧快照第四步观察恢复状态输出处理报告。写这类技能要特别注意安全边界。我明确在技能里写了“仅允许执行白名单中的动作任何涉及删除数据、变更权限、扩容资源的操作必须先向用户确认”。不是模型不聪明而是聪明反被聪明误必须用规则把动作约束好。3.5 个人知识管理类会议纪要和文档摘要的简化版如果你只想尝鲜最容易上手的场景是会议纪要和文档摘要。这类任务流程短、反馈快、试错成本低适合用来打磨你写技能的感觉。我常用的 meeting_notes 技能是这样的输入会议录音转文字文本或会议记录第一步抽取核心主题和讨论时间线第二步区分“决策”“待办”“风险”三类内容分别输出第三步每个待办必须带上负责人和截止时间如果没有明确标注“待确认”输出格式固定模板按决策、待办、风险分节。这个技能看起来简单但每次都能交付很干净的结果。原因就是它锁死了输出结构。模型不用再纠结“用什么格式展现”只需要专注于从原文里抽信息填槽位就行。如果你想验证技能库方法论是否适合你就从这一类小技能开始一周内就能看到明显的差别。4. 从零搭建技能库完整实操流程4.1 全局规划目录、命名与最低可用配置正式动手前先把地基打牢。我现在的推荐做法是新建一个独立的仓库或者目录专门放技能不要跟项目代码混在一起。这样技能可以被多个项目复用也方便用 Git 管理历史变更。初始化时只需要定四件事根目录统一叫 skills/内部按任务域分组每个技能一个子目录子目录内必含 SKILL.md可选含 examples/ 和 tests/技能命名采用“动作_对象”式小写下划线仓库根目录放一个 README.md说明技能库的使用方式和维护规范。bash命令大概是这样mkdir -p skills/{engineering,data_analysis,writing,operations} touch skills/README.md可能有人觉得这步多余但以我的经验前期不花十分钟定好结构后面整理成本会是十倍。技能库的目录结构本质上就是你团队“任务地图”的投影结构清晰模型匹配的准确率也会跟着高。4.2 编写第一个技能以“周报生成”为例空说理论没意思我直接演示一个周报生成技能的完整 SKILL.md这个技能我用了快三个月迭代了七个版本目前格式很稳定--- name: weekly_report description: 基于原始销售或运营数据生成结构化周报。当用户要求写周报汇总本周数据生成双周报时使用。如果用户提供的是互联网舆情而非业务数据不要使用本技能。 --- # Weekly Report Generator ## When to Use - 用户提供业务数据文件或数据表格要求输出周报 - 用户希望按固定口径汇总本周关键指标 ## Inputs Required - 数据文件CSV、Excel 或粘贴的表格文本 - 时间范围默认本周一至本周日 - 指标口径如果用户未指定使用仓库 docs/metrics.md 中的默认口径 ## Steps 1. 读取数据文件识别字段名和日期列 2. 按默认口径计算销售额、订单量、退款率、新增客户数 3. 对比上周数据计算环比变化率 4. 按模板输出报告 - 本周概览四个关键指标环比 - 异常波动说明超过10%的指标必须分析原因 - 下周展望与风险提示 ## Output Format ### 本周核心指标 | 指标 | 本周值 | 上周值 | 环比 | | 销售额 | ... | ... | ... | ### 异常分析 只列波动超10%的指标分析可能原因 ### 风险与建议 基于数据趋势给出风险判断 ## Quality Checklist - [ ] 所有指标是否按固定口径计算并在文中注明口径 - [ ] 空值是否超过10%超过则报告而未静默处理 - [ ] 环比变化是否计算正确 - [ ] 异常波动是否有原因分析是否避免编造归因这个技能看着长但每一节都有明确作用。front matter 里的 description 我花了很大心思因为在测试中发现如果 description 写得模糊模型会在用户只是闲聊“上周销量怎么样”时也去加载这个技能干扰正常对话。多写一句“如果用户提供的是互联网舆情而非业务数据不要使用本技能”能大幅降低误触发。正文里的 Quality Checklist 是技能的灵魂。模型执行完一切后会拿着这个清单逐项自检。我见过太多人写技能只写步骤不写检查项结果要么漏指标要么口径算错模型自己还没感觉。加了这个清单之后很多低级错误在输出前就被模型自己拦下了。4.3 给技能配几个例子few-shot 让行为更稳一个很实用的小技巧在技能的 examples/ 目录里放几组“输入—输出”样例。这里不是给人看说明文档而是让模型在处理真实任务前先看到一到两个高质量的完整示例。以周报技能为例我在 examples/ 下面放了三份不同的周报输出样例一份是正常周、一份是数据异常周、一份是数据缺失周。每个样例都严格按照 Output Format 来写。这样当模型读技能时它不止看到了规则文本还看到了“长这样才算合格”的具象参照。底层逻辑是模型对抽象规则的理解能力不如对具体示例的模仿能力强。你写十条“要有逻辑”不如放一条真的逻辑严密的范文。这个做法对内容类技能尤其明显我甚至见过一个写作技能只靠示例集就完成了行为校准自检清单都不用改。目录大概是examples/ ├── normal_week.md ├── anomaly_week.md └── missing_data_week.md记得三到五条高质量样本足够不需要堆数量。关键是覆盖不同边界场景而不是让模型看一百遍同一类输出。4.4 测试方法别等上生产再翻车技能写好不测试就上线等于穿着新鞋踩水坑——早晚得湿。我强烈建议所有技能至少跑一轮最小回归测试。所谓测试就是准备几条固定输入然后反复跑技能看输出是否稳定。我自己的习惯是为每个技能准备两个正例输入和两个边界输入比如周报的边界输入是空文件、全是空值的数据记录第一次跑的输出作为“基准输出”每次修改技能后重新跑同样的输入和基准输出对比看有没有退化如果技能逻辑变更导致预期输出变化主动更新基准输出。你也可以用脚本做半自动校验检查关键字段是否都在输出中。比如周报测试脚本可以检查是否包含四个指标、是否包含环比列、是否在异常分析中出现超过10%指标的说明。把这步自动化技能库的维护成本会大幅下降。# 简单检查脚本示例 required_sections [本周核心指标, 异常分析, 风险与建议] for section in required_sections: if section not in output: print(fFAIL: missing section {section})测试跑不跑差别是质变。我在早期没有测试意识一个技能改了 description 后偶尔触发条件就失效了直到用了很久才发现中间浪费了大量试错时间。现在所有技能改动都先走回归测试省心太多了。5. 技能不生效怎么办常见问题与排查实录5.1 速查表最常踩的六个坑我在实践中把踩过的问题整理成了速查表供你直接排查现象可能原因排查方法修复建议技能完全不被唤起description 语义覆盖不足用几个典型任务描述测试能否命中重写 description加入高频触发词和负面示例技能唤起了但行为走样步骤描述太抽象模型自由发挥检查 Steps 是否每步都有明确输入输出把步骤改写为“动作产出”句式多个技能互相抢触发description 边界不清晰查看各技能 description 关键词重叠情况在每个技能 description 里加“非适用场景”技能内容太长执行时上下文爆炸技能文件里塞了过多背景知识统计每次触发后消耗的 token 数把过长的统计口径、规则等拆到外部引用文件改了一个技能别的技能出问题技能之间共享了秘密依赖检查修改技能是否被其他技能显式引用保持技能目录独立不做互相引用或建立版本兼容说明同一次任务反复加载同一技能技能内步骤要求不一致导致模型反复改稿检查步骤间的连贯性和自检逻辑把中间产出物的格式锁定减少模型重做的空间这个表不能光存着真出问题时建议按顺序排查先看触发、再看步骤、再看输出模板。大多数问题出在前两步步骤写不清楚后续全白搭。5.2 触发失败的隐藏原因description 的“负样本思维”很多技能触发不了不是因为它不该触发而是因为 description 没给模型“足够的判别依据”。模型加载技能是一个相似度匹配过程你的 description 越模糊模型的判断方差就越大。解决思路是引入“负样本思维”在 description 里除了写“什么情况下用”再加一句“什么情况下不要用”。上面的周报技能就是这么干的。我测试过很多次有了这行负面条件后误触发率显著下降。再往深处说一个技能触发失败还有一个常见原因description 里全是大词没有动作词。比如“数据分析”这个词就比不上“计算销售额”“生成周报”这种带动作的短语。模型对动作词的语义表征更敏感所以我会刻意在 description 里放两三个动词短语。这个方法对任何技能都有效。5.3 行为漂移的排查把技能当代码来看技能文件和代码一样是有“版本回归”的。你改了一个检查清单的措辞可能表面看意思不变但模型实际执行时的行为就是变了。这在自然语言场景里特别现实因为语义是连续的而代码只有0和1。所以排查行为漂移时我的操作方法是打开 Git 历史对比最近一次改动到底动了哪些字段。如果是措辞变了但意图没变先回滚看是否解决如果回滚没解决再用测试输入跑多个轮次观察输出差异在哪里。这些事情做完通常能定位到具体问题。但还有一种情况要警惕模型版本升级也会导致行为漂移。同一个技能换一个更强的模型可能因为模型本身的推理倾向变化输出方式就跟原来不一样了。这不是你写错了而是执行环境变了。遇到这种情况需要做的是重新跑基准测试然后针对性调整技能措辞而不是怀疑自己整个方法错了。5.4 技能文件越长越好的误区模块化组织不只是为了好看也是为了让模型执行时只加载它真正需要的那部分信息。我一直强调技能文件不是文档库不是越长越专业。一个 SKILL.md 如果超过2000字就该考虑拆分或者外置了。长文件的问题在于模型对长文本的注意力会稀释后半部分的规则经常被“忽略”。你可以测试一下就知道了把输出格式放在技能文件的第100行执行时经常会被模型简化掉。现在我的牵头原则是正文里只写步骤、输出格式和检查项所有补充说明、示例、统计口径细节能外置就外置。6. 把技能库变成团队资产版本化与评测体系6.1 用 Git 管理技能注释要能追溯技能库本质上是一套代码资产理所当然要用 Git 管理。这个过程没什么神秘可言但有三条我在实践中养成的硬规则也许能帮你少走弯路每次改动一个技能都必须更新前的事先在 front matter 里加 version 字段比如 version: 1.4.0commit message 里写清楚“改了什么指令、为什么改”方便团队其他成员追溯如果技能对模型版本有依赖在 README 里标明“已验证的模型版本”。这里的核心逻辑是技能会随你和团队的实践不断演进没有一个版本是终版没有记录就没有演进。我见过一个团队因为技能没有版本管理改坏了一个生成模板过了两周才发现线上一直在输出带错别字的报告排查成本极高。加了版本管理之后任何问题都可以在两分钟内定位到是哪次变更引入的。6.2 技能评测用打分表替代“感觉还行”技能写得好不好不能靠感觉必须量化评估。我团队内部现在用的是四维评分表维度评分标准权重触发准确率20个典型任务描述里能准确唤起技能的比例25%步骤完整率技能定义的关键步骤在实际输出中是否全部完成35%输出规范符合率输出是否符合模板字段、格式与口径30%回归稳定率相同输入重复3次的结果一致性10%每月抽检一次低于80分的技能要进入重写流程。这个评分机制最大的好处是把“我觉得它还行”这种模糊感受变成可量化的数据让每一次技能迭代都有依据。你会发现很多你以为好用的技能真到打分的时候居然不及格这就是评测的意义。6.3 个人技能到团队资产需要配套的治理机制技能库如果只是一个人在用你可以随意改。但一旦要给团队共享就要引入最基本的治理机制。这里说的治理不是搞复杂流程而是做三件事第一每个技能指定一个 owner负责回答问题和接受修改建议。第二修改技能前先写 changelog 说明也先跑回归测试通过后再合并。第三定期对技能库做健康检查把三个月内一次都没被触发过的技能标记为“废弃候选”避免技能库变成垃圾堆积场。团队协作里面最容易出现的问题是重复造轮子。两个工程师可能因为不知道对方写了类似技能各写一个高度重叠的版本。为了避免这种情况我要求新技能提交时必须先在仓库的 issue 里登记任务类型如果已有相近技能owner 会来联系你进行合并或补充。这种做法看起来有点多余但长期执行下来技能库会越用越干净而不是越用越乱。6.4 技能会不会过时模型升级后的再验证最后说一个容易被忽略的问题技能会随模型能力升级而过时。旧模型需要你写“请逐步思考”这种提示新模型可能不再需要新模型支持的上下文长度翻倍你可能就敢把原来拆出去的口径文档重新内联进来让执行更稳定。所以技能库的主人在模型重大升级后应该主动做一轮回归验证。不需要全部重写但凡是高频使用的核心技能跑一遍基准测试确认输出没有出现行为漂移。必要的话根据模型能力变化调整技能粒度。我在 Claude 新版本发布后实测过自己的技能库有的技能因为模型能力变强原来需要三步完成的任务现在两步就够了也有的技能因为模型更倾向“自由发挥”反而需要加强输出模板约束。这都正常关键是形成一种持续验证的习惯。技能库不是一次性交付品它是一条成长中的生产线。你得定期维护、调整、淘汰、更新才能保证它始终产出稳定可靠的结果。回想这一路踩过的坑我最深的体会就是不要试图一次写好一个万能技能先写三个窄技能让它们跑起来再逐步迭代。技能是“用”出来的不是“写”出来的。等到你的技能库有了几十个高质量技能你会明显感觉到智能体从“偶尔帮我省点事”变成了“一个真正靠谱的数字同事”。