1. 一个真实的翻车现场写了SkillAgent还是不听上个月我花了一个下午给团队常用的AI编程助手写了一份挺详细的代码审查Skill。SKILL.md里规定了审查重点、检查顺序、错误分级标准甚至连什么样的问题算阻断、什么样的问题算建议都写成了表格。我信心满满地提交然后在一次真实的Pull Request审查里Agent打开改动文件盯着diff看了一会儿然后给我提了一堆这个函数命名可以更清晰之类的泛泛之谈。最关键的一个安全问题——用户输入的SQL拼接——它压根没提。那一瞬间我的第一反应是这玩意到底有没有用。如果你也遇到过类似的情况或者正犹豫要不要给Agent写Skills这篇文章就是写给你的。我不打算全盘吹Agent Skills怎么神也不打算一棍子打死说它没用。我打算从机制、实操、调试这四条线把这个东西掰开用我自己踩过的坑说明Agent Skills这东西本质上是给Agent写操作手册它有用但它的有用方式和绝大多数人想的不一样。先说清楚一个概念Agent Skills指的是在Claude这类具备Agent能力的AI助手里通过本地文件系统预置的SKILL.md文件来给Claude注入领域技能。文件放在.claude/skills/技能名/SKILL.md这个路径下里面用Markdown写上技能的触发条件、使用步骤、注意事项和示例。Claude是个典型的长文本工具使用型模型它在执行任务时会先扫描可用的Skills遇到跟当前任务匹配的就会主动加载这份操作手册来指导行为。但加载了手册和手册真正生效是两码事。那次代码审查失败的根因我后来复盘时发现有两个一是我的Skill描述写得太模糊Agent根本没在合适的时机判断出这个任务该用这个Skill二是Skill正文里塞了一堆原则性的东西缺少可执行的分步清单Agent读完以后相当于没读。这两个坑几乎每个第一次写Skills的人都会踩后面我会展开讲怎么避。在开始之前先把结论丢给各位给AI编程助手写操作手册有用。但它不是用来增强模型能力的而是用来约束模型行为和沉淀团队规范的。你把这句话理解到位了使用方法自然就对了。接下来的篇幅我来解释为什么会得出这个结论以及一份真正能用的Skills应该怎么写、怎么测、怎么迭代。2. 先搞清楚Agent Skills到底在解决什么问题想判断一个技术方案有没有用得先看它解决什么痛点。Agent Skills解决的问题和普通Prompt、Tool、MCP解决的问题有交集但侧重点完全不同。我用一个对照表先把阵营拉开方案类比解决的问题System Prompt给新员工做的入职宣讲设定总体的行为准则、语气、边界Tool / Function Call给新员工发一把电钻赋予调用外部函数、获取数据的能力MCP给新员工接通公司内部各个系统统一数据和服务访问的端口Agent Skills给新员工发一本岗位SOP手册沉淀这个活具体该怎么干的操作知识从这个类比可以看出来Skills的定位非常特殊它不直接给模型增加能力而是增加工作方法。2.1 Skill是操作手册不是能力包大多数人第一次接触Agent Skills时会有个预期我把最佳实践写进去Agent的执行质量应该能立刻变强。这个预期在很多时候是落空的因为一个Skill真正改变的不是模型的推理上限而是它做具体任务时的动作序列。举个数据相关的例子。我写过一个数据探索Skill里面规定拿到数据集先看shape和dtypes再统计缺失值比例超过5%的字段要在报告中单独说明然后才是画分布图、做相关性分析。这套流程一个合格的数据分析师闭着眼都会但AI助手如果没有人给手册它大概率上来就是一通df.describe()、df.corr()然后给你丢一个图表堆砌物。跑出来的东西不算错但很不像专业分析师的工作习惯。这就是Skills的第一层价值把团队里老师傅的工作流变成显性的、可复制的操作步骤。模型自己是不会总结出一套我们团队认可的工作方法的你得写给它。它不需要Skill也能干活但有Skill的时候干活的方式更接近你的预期。2.2 加载机制Skill是按需翻阅不是每轮硬灌理解Skills的另一个关键点是它的加载方式。System Prompt是每轮对话都要进上下文的它会持续占用注意力所以你不能把一大本SOP塞进System Prompt里Tools是模型可调用的接口但调用接口不等于知道怎么组合这些接口去完成一个复杂流程Agent Skills则不同Claude会根据当前任务内容自动决定要不要找这份手册来读。这个机制的好处是省token、省注意力。但坏处也很明显——它依赖模型的判断力来触发阅读。如果你的Skill描述写得不好模型判断不出这个任务该用它那这个Skill就形同虚设。所以我后面会专门讲description字段怎么写才容易唤醒Agent。2.3 Skill和MCP的分工一个管怎么连一个管怎么干MCPModel Context Protocol最近在AI圈讨论度很高很多人会把Skill和MCP搞混或者觉得有了MCP就不需要Skill了。我的理解是这俩压根是互补关系。MCP解决的是模型怎么访问外部数据和工具的问题。它是一套协议让Claude能够以标准的方式连接到GitHub、文件系统、数据库这些资源。但连上数据库之后怎么围绕这些数据产出符合规范的报表MCP不管这个。Skill管的就是这一段它规定操作流程、报告结构、检查要点。打个比方MCP是你给员工开通的内部系统账号Skill是员工入职第一天拿到的工作手册。账号决定他能进哪些门手册决定他进门以后该干什么、按什么顺序干、干完交什么东西。两者缺一不可。所以我的建议是在接入MCP之前或同时先把手边那些重复性高、流程稳定的任务写成Skill。器人调得再好流程没有固化下来每次都是模型自由发挥输出质量就很难稳定。Skill的本质就是给自由发挥驯装一道轨。3. 手写一个实战Skill把研发团队规范做成SKILL.md概念聊完来点实操。我拿代码提交信息规范Skill来做例子因为这个场景几乎每个开发者都熟而且足够简单可以完整体现一份SKILL.md的写法。我给Skill建的标准目录是这样your-project/.claude/skills/commit-msg/SKILL.md注意commit-msg是这个技能的名字目录名和技能名保持一致。一份SKILL.md通常由两部分组成YAML格式的frontmatter元信息和Markdown格式的正文操作指南。3.1 完整的SKILL.md示例下面是我实际在用的一个精简版用于让AI助手帮团队生成符合规范的Git提交信息--- name: commit-msg description: 根据git diff生成符合团队规范的commit message。当用户要求提交代码、生成提交信息、写commit message时使用。生成的信息需遵循Conventional Commits规范。 version: 1.0.0 metadata: author: team-dev --- # Commit Message生成技能 ## 使用时机 - 用户要求提交代码、帮我commit、生成提交信息时 - 用户要求为已有改动生成Pull Request标题和描述时 ## 工作流程 1. 先运行 git diff --cached 查看已暂存改动如果没有暂存内容运行 git diff 查看工作区改动 2. 按改动文件的功能归类识别出本次提交的主体类型feat/fix/refactor/docs/test/chore 3. 检查是否有破坏性变更若有必须在commit message中加 BREAKING CHANGE: 说明 4. 生成格式type(scope): subject如 feat(auth): 增加邮箱验证码登录 5. subject使用祈使句、不超过72个字符不要以句号结尾 ## 输出格式 - 若改动涉及多个功能类别按type分组输出多条commit建议 - 在commit message后附一段中文说明简述每条建议的理由 ## 边界与注意事项 - 不要提交未暂存的文件 - 如果diff为空直接告诉用户没有可提交的改动不要强行生成 - 生成的commit message中不要出现AI生成痕迹的套话如优化代码这种无信息量的表述3.2 写好frontmatter比写正文更关键很多新手写SKILL.md时最容易忽视的就是开头的YAML部分。你可能会觉得description只是给人看的摘要随便写两句就行。但实际上description决定了Agent会不会在正确的时候读这份手册。Claude的加载逻辑是这样的拿到用户请求后它会扫描已经安装的Skills列表根据description里的内容判断这个Skill和当前任务的匹配度然后再决定要不要打开SKILL.md。这个判断非常依赖description里出现了哪些关键词和场景描述。拿上面这个例子来说我在description里明确写了触发场景提交代码、生成提交信息、commit message同时又写了功能边界根据git diff生成符合团队规范的commit message。这样Agent在读这个Skill列表时能快速判断用户要提交代码这个Skill可能相关。如果你只写一句用于生成commit messageAgent也不至于完全找不到但触发准确度会下降不少。另外一个容易被忽略的点是一个目录下面可以放多个技能也可以在不同的子目录里放配套资源。按照官方实践如果你需要给Skill附上模板文件、示例数据可以放在SKILL.md同目录下然后正文里用相对路径引用。这样打包分享时所有东西都在一个文件夹里不会散落各处。3.3 正文结构先给流程再给边界SKILL.md的正文我建议按这个顺序来组织使用时机什么场景下该用、什么场景下不该用。这一步是为了防止错误唤起非常重要。AI工具的特点是你给它的空间越大它越容易跑偏明确边界能省掉大量返工。工作流程按步骤号列出从开始到结束的动作序列。步骤要足够细但不要细到把模型的每一步思考都规定死。我一般每个步骤控制在动作产出两句话以内比如运行命令查看改动、按类别归类提交类型。输出格式定义结果长什么样。AI编程助手生成的代码、提交信息、报告都有被下游直接消费的需求你这里定义得越明确后面的人工校对成本越低。边界与注意事项这是很多人忽略的部分。把容易踩的坑、绝对不能做的事写在这里比如不要提交未暂存的文件、diff为空时不要强行生成。它可以显著降低Agent的自作主张率。我遇到过最典型的反面教材是一个人把Skill写成了几千字的论文前面五段都在讲什么是好的代码注释讲到第六段才进入实操。Agent读完以后记住的是抽象原则执行的时候依然我行我素。正确做法是把可执行的步骤放在最前面把原则解释放在最后或直接删除。Agent需要的是指令不是论文。4. 有用还是没用真正的分水岭在这三个维度回到标题那个核心问题给AI编程助手写操作手册到底有没有用经过这段时间的反复测试我的答案是有用但作用范围比很多人想象的要窄。一个Skill有没有效果我总结了三个判断维度。4.1 第一维任务流程是否稳定这个最简单也最关键。如果你要固化的任务是每次步骤都一样、判断标准相对固定的Skill的效果立竿见影。比如提交信息生成、测试用例编写、日志规范化、代码格式检查这些任务的共同点是流程固定、评判标准清晰写清楚步骤后Agent的执行一致性会大幅提升。反过来如果任务是高度探索性的比如帮我设计一个新产品的架构、写一段充满创意的营销文案这种任务本身没有标准流程你硬套一个Skill上去反而会限制模型的发挥空间。我试过一个失败的案例给一个系统架构设计Skill规定了必须先写需求分析、再画模块图、再写接口定义结果生成的方案明显变僵了模型为了符合流程而把真正重要的设计权衡稀释掉了。对这种探索类任务我更推荐用普通的对话提示词让模型自由发挥然后人工介入讨论。4.2 第二维规则是否可以被显式表达有些知识虽然流程固定但只可意会不可言传。比如代码味道一个有经验的开发者看一段代码能感觉出哪里不对但很难用几条规则总结出让AI照做的标准。这种情况写Skill就很为难你写得太细模型会被条条框框束缚写得粗模型行为跟没写差不多。有个折中的办法把负面清单写进Skill。不要试图定义什么是好的而是定义什么是不允许出现的。比如给代码审查Skill写清不允许出现魔法数字、不允许吞掉异常、不允许修改与本次需求无关的文件远比写十句请注意代码质量这种正确的废话有用得多。负面清单天然是显式的、可检查的模型执行时更容易对齐。4.3 第三维Skill与工具的配合深度如果你的任务需要和外部环境交互比如操作浏览器、调用API、修改数据库单独写一个Skill是不够的。Skill只规定怎么做但用什么做需要Tools和MCP来提供。我做过一个自动化测试Skill里面要求Agent打开浏览器登录系统运行冒烟测试用例结果模型严格遵守了但没有可用的浏览器工具于是卡在原地。这个教训让我意识到Skill是手册不是工具箱。写Skill之前你得先确认Agent已经具备完成这项任务所需的工具集。如果工具没接通Skill写得再详细也只能生成一个纸面流程无法真正落地。实测下来Skill加一个能配合它的MCP服务效果会出奇的好一个是流程规范一个是能力基座两者拼起来才能让Agent像模像样地独立干完一件复杂事。5. 让Skill真正被用起来的调试经验说一千道一万写Skill只是第一步真正能拉开差距的是调试和迭代。这个环节里坑最多我捡几个重点说。5.1 调试Skill的唯一正确方式固定输入反复跑我自己调试Skill时绝不会让Agent随意干活而是准备一组固定测试样本三个典型的正例、两个典型的反例、一个边界场景。每次改完SKILL.md我就把这套样本重新跑一遍对比输出差异。比如调试代码审查Skill时我准备了一个故意含有SQL注入极脆弱写法的PR一个违反团队命名规范的PR还有一个完全没问题的PR。每次改描述或者步骤我就看这三个样本上的行为变化。这套方法比凭感觉调Prompt靠谱一百倍因为它能让你看清楚这次改动到底改变了什么。如果三个样本的结果没有明显变化说明改动没作用果断回滚。改Skill的频率也要克制。一次只改一个变量改完跑全套样本不要攒十处改动一起上——否则你根本分不清哪处改动导致了哪个行为变化。这和调试代码是一个逻辑。5.2 给description做召唤词设计我在前面提过description的重要性这里再具体一点好的description应该包含任务识别词和应用场景句两部分。举个例子。我有一个数据分表设计Skilldescription一开始写的是用于数据库分表设计结果老是不被触发。后来我改成description: 当用户提到分表、分库、数据量太大查询慢、表数据增长过快等场景或要求设计数据库水平拆分方案时使用。提供分表键选择、拆分策略、迁移方案。加了这些召唤词之后触发率肉眼可见地提升。原理很简单Claude扫描Skill描述时就像一个搜索系统你的description里有哪些关键词决定它能不能被搜索到。所以我会建议把你期望用户说的词、以及任务涉及的核心概念尽量都写进去但不能堆砌无关关键词。5.3 一上来先做手动加载再过度到自动触发新写的Skill先别急着依赖自动触发。我在.claude/skills/目录里加了一个临时的activate-manual技能里面只写了一句话使用前必须告知用户已激活技能{技能列表}请确认是否继续。这样我测试新Skill时Claude每次读Skill都会先告诉我它认为该用哪些技能我就能直观看到它的技能选择是否合理。如果Agent干一个要求代码格式化的活却选了数据分析Skill那说明召唤词写歪了。等测了几轮触发准确率稳定了再把这个调试辅助技能删掉。5.4 常见坑清单把这段时间踩过的坑做个汇总这些都是别人文档里不会写的实操细节SKILL.md过长。我有一次写了一个超长Skill结果加载后行为反而变差。实测下来单个Skill正文建议控制在3000字以内核心步骤和负面清单优先修辞和背景介绍能删就删。如果确实内容多拆成两个Skill各自聚焦一个场景。多个Skill职责重叠。当你有两个Skill的描述都能覆盖同一个任务时Agent会随机选一个行为就变得不稳定。解决办法是让每个Skill的任务边界尽量唯一相互之间用不使用时机来隔离。只写应该不写禁止。模型的特性是顺从指令你写的应该它会执行但你可能忘了它也会执行很多你没提的不应该。禁止放宽文件权限、禁止使用mock数据冒充真实测试结果这种负面清单往往比正面描述更有效。版本管理缺失。Skill迭代是常态建议在一个文件头部用YAML维护version字段并在改动日志里保持简短的变更描述。回滚的时候你至少知道上一个稳定版本长什么样。6. 从调提示词到沉淀技能我的几点体会最后不打算搞什么总结升华聊点实际的体会。Agent Skills这个东西真正有价值的不是让AI更聪明而是把团队的工作规范从人的脑子里搬到仓库里。以前新人来了要跟着老师傅学两三周才能写出发规范、查得出问题的PR现在老师傅把工作流写成一个SKILL.mdAgent立马就能按这套标准干活。规范的沉淀、复用、迭代这套机制做得比纯Prompt工程优雅得多。但也要承认它的边界。它不是万能的在高度探索性的任务和只可意会的领域知识面前它帮不上太多忙。我自己的用法是在团队里先挑那些流程稳定、产出标准明确的任务试点跑通三五个Skill之后整个团队的AI协作质量会明显变得稳定迭代和维护成本也低。如果你准备动手尝试我建议从最小的一个Skill开始写起。找一个你每周都会重复两三次、且每次都要跟AI重复解释需求的任务把它固化成一份SKILL.md。写完测三遍如果稳定了就提交到团队仓库里。你会发现写第一份Skill最大的障碍不是技术而是你对自己工作流中隐性步骤的觉察程度——当你真正开始把这些步骤逐条写出来时你对操作手册到底有没有用的答案会比任何评测都更清楚。