Agent Skills实战:SKILL.md与自定义技能,让Agent变好用 “skills”这个词最近在AI圈子里火得有点离谱各种“skills推荐”“skills大全”“skills开发”的帖子满天飞但大部分人其实还停留在“听说过、没用过、不知道怎么上手”的阶段。我自己从Claude的Agent Skills文档啃到Codex的实际应用又亲手折腾了几个自定义skill中间踩了不少坑才慢慢搞清楚这套东西到底在解决什么问题、应该怎么用。这篇文章不打算做概念搬运就想把“skills到底是个什么玩意儿、它为什么能让Agent从‘能用’变成‘好用’、以及你该怎么自己做一个skill”这几件事讲透。我默认来看这篇文章的你已经用过至少一款AI编程工具比如Claude、Codex、Cursor这类知道Agent是什么但可能对skills机制还比较懵。如果你连Agent都不太了解也不慌下面的解释会尽量从底层逻辑讲起保证你看完能直接上手。1. 为什么Agent的skill不只是“写个prompt”那么简单先说个反直觉的结论很多人在接触skills之前都以为它就是把一段系统提示词或者一个prompt模板封装起来方便复用而已。我第一次看到SKILL.md这个文件名的时候也差不多是这么想的。但实际用下来你会发现如果只是把它当“高级prompt管理工具”那完全低估了这套机制的价值。1.1 Agent的真正瓶颈不是“不会说话”而是“没有工作记忆”如果只靠上下文对话让Agent完成“写一篇深度技术文章”这种开放式任务它往往会出现几个让人抓狂的毛病聊着聊着忘了最初的要求、中间突然换了文风、写到一半开始自创结构、生成的内容虽然单看合理但整体根本不像“一个人写出来的东西”。说白了没有外部记忆和结构约束的Agent像是一个记性很差但嘴皮子很溜的临时工。而skills机制的核心思路是给Agent配了一份“岗位说明书 工作手册 工具箱”。它不只是告诉Agent“你是个文章写作专家”而是明确规定了你写文章之前必须先做调研、先搭骨架、每段最小字数是多少、使用什么风格的口吻、禁止出现哪些词、完稿之前要自查几遍。这些内容不靠聊天记录里的“临时约定”来维持而是作为一个固定的、可调用的程序化模块存在。这就像你去一家公司面试老板嘴上跟你说“我们这边需要你干活积极主动”是不算数的真正有效的是公司给你发了员工手册里面写了上下班时间、报销流程、汇报层级。skills承担的就是员工手册的角色——把“口头期望”变成“书面规则”。1.2 提示词注入 vs 系统级调用两者有本质区别还有一种误解是“我不需要skill我在对话里写清楚要求不就行了”短期用一个任务确实没问题但这里有几个隐藏成本上下文窗口占用长篇的规则说明会挤占有限的上下文空间。比如一个详细的文章写作规范可能有2000字这2000字如果每次都要在主对话里重复粘贴成本极高。而skill是按需加载的Agent只在需要执行这类任务时才读取对应文件。规则一致性你在对话里写的规则Agent在执行过程中可能因为新信息的加入而“忘记”或者“稀释”。但skill里存放的规则每次被启用时都是全新读取的不会因为聊了几十轮之后权重变低。可维护性你给10个不同的Agent分别口头交代了一遍写作规范和统一维护一个写作skill文件哪个好改显然是后者。改一处所有调用这个skill的Agent全部生效。1.3 用“传武”类比理解skills招式和内功的区别我记得有个老程序员说过一段特别贴切的话单纯的prompt是“招式”你见招拆招但遇到没见过的场景就不行了skill是“内功 招式库”它规定了你的发力方式、呼吸节奏以及遇到什么情况自动切换什么招式。正是因为有了这套体系Agent才能在一个较长周期的任务里保持稳定输出而不是每次生成都“重新做人”。从这个角度来看skills面向的其实是“让AI Agent变成真正能交付复杂任务的执行者”这个目标而不是简单的问答工具。如果你手里有那种“需要Agent一口气干完好几个步骤、中间涉及多种工具调用”的任务那你基本就需要开始研究skills了。2. skills的真实载体从项目结构到SKILL.md的运作机制想真正理解一个技术方案光看概念不行得钻进文件结构里去看。这一节我会用一个实际的skill项目结构作为例子把每个文件的作用讲清楚。你可能会发现原来一个skill的骨架比想象中简单但正是这些细节决定了它好不好用。2.1 一个最小skill项目长什么样按照官方文档和社区实践一个标准的skill至少包含一个SKILL.md文件通常还会附带脚本文档和引用资源。下面是我自己搭建过的一个“技术文章写作专家”skill的目录结构article-writing-skill/ ├── SKILL.md # 技能定义文件必填 ├── scripts/ │ └── article_check.py # 用于检查文章字数和结构的辅助脚本 ├── references/ │ └── style_guide.md # 写作风格指南SKILL.md中会引用 └── assets/ └── templates/ └── article_template.md # 文章骨架模板初看这个结构你可能觉得有点小题大做——一个写作skill而已用得着脚本和模板吗但如果你仔细想一下Agent的执行方式就会发现这恰恰是它区别于“一段prompt”的关键。2.2 SKILL.md内部的核心字段分别解决什么问题SKILL.md采用YAML frontmatter Markdown正文的格式有点像GitHub README配合Jekyll的写法。frontmatter部分通常长这样--- name: article-writing description: 用于创作高质量技术文章。当用户需要撰写深度稿件、技术博客或长文时使用。 ---name是唯一标识description是触发条件。这里的细节很多人会踩坑description写得越具体Agent越容易在合适的时候自动唤起这个skill。你可以把它想成一个“钓鱼饵料”Agent在收到用户请求之后会拿这个description去匹配当前任务。如果你写得太泛比如“处理文本”Agent几乎永远不会主动用它写得太窄又有可能该用的时候不用。2.3 正文才是灵魂行为流程、规则清单与自查清单frontmatter下面的Markdown正文我用三个大块来组织工作流程、规则、输出要求。工作流程部分我明确要求Agent必须先做“读者画像分析”然后“列出大纲”得到用户确认后“开始写作”完稿后“运行检查脚本”。这一步的本质是把一个模糊的“写篇文章”任务拆解成几个明确的子任务序列让Agent知道自己每一步该干什么。规则部分我写了十几条非常具体的禁令和要求比如“禁止使用AI套路化表达”“每段不少于150字”“禁止输出元信息”“不要使用Emoji”等。这些规则如果只是放在对话里很容易被长上下文冲淡但在SKILL.md里它们会在任务开始时被完整加载优先级很高。输出要求部分我甚至定义了Markdown的标题层级规范要求H2以上标题必须带编号。为什么要这么细因为你如果不明确规定Agent给出的文章结构可能五花八门有的用“一、二、三”有的直接用加粗做标题有的甚至不写小标题。你只有把边界划死它才能稳定输出你真正想要的格式。2.4 skill与“子Agent”“插件”到底什么关系很多人会把skills和子Agentsub-agent或者插件plugin混为一谈这里需要做一个简单区分插件/工具提供Agent可以调用的外部能力比如浏览器搜索、执行代码、读取文件。它们解决的是“Agent的手不够长”的问题。子Agent一种将任务委派给某个独立Agent实例的处理方式通常有独立的上下文窗口和系统指令解决的是“单一上下文不够用”的问题。Skills更接近“操作规范”它不提供外部能力而是训练Agent“如何更好地利用已有能力”。它解决的是“Agent做事没章法、没套路”的问题。我用一个生活化的比喻插件是给你一把电钻子Agent是给你请了个装修师傅而skill是交给装修师傅的一本《精装房施工标准》。三者可以配合使用但职责完全不同。2.5 帮技能栈“立规矩”的开源项目在热门词里看到了“superpower skills”和“superpowers 具体使用”这些关键词。这里多提一句社区里现在有不少人把一组设计良好的skills组合叫做“superpowers”意思是这些技能叠加之后能让Agent的执行力上一个台阶。比如“规划型skill 执行型skill 审查型skill”的组合会让Agent在一个大任务里先做计划再逐步执行最后自检修正整个链路完整得像个成熟员工。我自己试用下来最大的感受是一套好的skills组合会迫使Agent“慢下来”。它不再是一上来就写代码、写文章而是会先调用规划类skill给自己列步骤再逐步推进。这个过程看起来变慢了但实际上返工率大幅下降最终交付时间反而更快了。3. 手把手做一个可复用的skill从需求拆分到发布理论说了那么多这一节直接进入实战。我会以我自己做过的“论文结构优化”skill为例完整走一遍从需求分析到最终发布的流程。你要是有自己的场景照着这个思路套就行。3.1 第一步把你的任务拆成“可书写的工作流”动手写SKILL.md之前先别急着打开编辑器先回答一个问题这个skill要解决的典型任务到底是什么它包含哪几个固定步骤以“论文结构优化”为例我把它拆成了五步分析论文当前结构识别逻辑断层和论点单薄位置。根据学科领域特点输出优化后的章节大纲。对关键段落给出具体的改写建议而不是只做泛泛点评。检查全文是否存在引用不规范、论证跳跃、摘要与结论不一致等问题。输出修改优先级列表让用户知道先改哪里。这几个步骤是固定的Agent每次接到类似任务时都会先按这个流程走。这就是skill存在的意义——你不需要每次对话都重新跟Agent解释一遍什么叫“结构优化”。3.2 第二步把“经验”翻译成“机器能执行的规则”把流程列出来只是第一步难点在于把那些你脑子里的“下意识判断”变成Agent能理解的显式规则。比如我自己写论文时有一套默认的判断标准摘要应该包含背景、方法、结果、结论四个要素引言必须有明确的“研究缺口”描述结论不能只是复述正文必须有总结和展望。这些如果不写进skillAgent永远不知道你在说什么。我当时在SKILL.md里把这些规则写成了“检查清单”一个字段对应一个检查项并给出合格与不合格的判定示例。这一步有点像在给新手评审专家做上岗培训——你不光告诉他“要看得分点”还得告诉他“什么情况算得分点”。3.3 第三步设计“辅助脚本”让skill具备硬校验能力文字描述得再清楚Agent执行时还是有可能“漏判”。所以我在scripts目录里放了一个structure_checker.py它做几件简单但特别有用的事解析Markdown标题层级检查有没有跳级比如从##直接跳到####。统计每个H2小节下的正文字数低于阈值就直接输出警告。检查全文是否出现Emoji、是否出现禁用词。生成一份报告告诉Agent哪些位置需要修改。为什么script很重要因为大模型在自由生成时对“精确数字”的把握比较弱让它“确保每段不少于150字”不如让它“跑一下脚本检查字数”靠谱。人的短期记忆不靠谱模型也一样你给它一个明确的外部校验工具它才会老老实实执行。3.4 第四步用“few-shot示范”兜底降低理解偏差除了流程和规则我还在references里放了一个examples.md里面有两份对比左边是“不符合要求的段落”右边是“修改后的段落”中间标注了修改理由。这个文件的目的是给Agent提供“参考坐标”让它知道“达标”到底长什么样。这个大招是我在测试中发现特别有用的。原因是很多Agent的问题不是“不懂规则”而是“不知道规则的执行标准”。文字描述“要口语化”和给一个口语化的具体例子之间隔着一个巨大的语义鸿沟。有了示例子样本Agent的输出水平一下就稳定了。3.5 第五步发布与测试前自查skill文件写完之后先别急着到处分享按下面的清单自查一遍name字段是否唯一且容易记忆description是否覆盖了你希望触发的典型任务场景正文的工作流是否从“用户具体请求”直接映射到“可执行步骤”规则是否互相矛盾比如既说“允许幽默”又规定“禁止轻松语气”引用文件路径是否真实存在、大小写是否匹配有没有在skill里依赖“对话历史里出现过的东西”这会让skill无法独立运作这个清单帮我避免了好几次自己把自己带沟里的情况。尤其是最后一条新手最容易犯很容易在skill里写“结合我们之前讨论过的XXX”但skill被调用时Agent的当前上下文里可能根本没有“之前讨论过的东西”执行效果自然稀烂。4. 安装、管理和测试让skills真正跑起来的完整链路写完skill只是第一步怎么装进去、怎么让它在合适的时机被启用、出了问题怎么排查这些环节其实才是日常使用中真正花时间的地方。这节我把不同工具下的安装与调试经验都梳理一遍。4.1 官方市场与本地导入两条常见的安装路径现在主流的Agent工具都内置了skills功能的支持比如Claude有官方skills目录Codex也支持类似机制。安装skill通常有两条路径路径一从官方市场直接安装这是最省事的办法。打开市场的搜索框输入技能名称比如“article-writing”或“paper-optimizer”点安装即可。安装完之后Agent会在配置目录下生成对应的skill文件夹之后你就能在Agent的设置界面看到它。这种方式的好处是不用关心文件放哪儿、权限怎么配坏处是官方市场里高质量的skill数量还比较有限很多你可能还是得自己写或者从社区下载。路径二手动导入本地skill文件夹把下载或自己写的skill整个目录复制到Agent的skills配置目录里。具体路径因工具而异Claude桌面版一般是在用户目录下的.claude/skillsCodex也有类似的~/.codex/skills。复制完之后重启一下客户端让它重新扫描目录。这个方法进阶用户必须掌握因为真正的自定义skill几乎都是通过这个方式加载的。表格对比一下两种方式对比维度官方市场安装本地手动导入上手难度低中可定制性低只能用现成的高可随意修改适用场景快速体验生产环境、自研技能常见问题技能描述与需求不匹配目录或文件名识别失败4.2 为什么Agent“无视”你的skill触发条件排查装完skill之后最常见的问题就是我明明装了为什么它好像完全不存在这种“无视”通常有三个原因。第一个原因是description写得不好。前面说过了Agent通过description来决定是否启用skill如果你的描述和用户实际需求的对齐度不够它就启用不了。比如你的description里写的是“用于优化论文结构”用户说“帮我把这段改得更有逻辑”这两个描述之间的匹配度可能就不够Agent就不会调用这个skill。第二个原因是上下文不够。部分工具只有在主对话上下文快要溢出时才启用skill机制如果你的任务很短它可能觉得没必要动用“专业职业技能包”。这个机制本身是优化体验但有时也会让人误以为skill失效了。第三个别工具在“普通对话模式”下是不会主动调取任何skills的必须在Agent模式或者指定模式下才会工作。所以如果你用的工具刚更新了界面不妨去设置里看看当前的运行模式对不对。我自己的排查套路是直接创建一个“故意包含该skill关键词”的测试任务看Agent的回复开头或内部推理过程中有没有提到“根据skill中的规则”。如果没有我就先检查trigger的description是否够具体再检查是否指定了正确的模式一步步排除。4.3 测试框架你不需要写代码也能测skill既然涉及调试就离不开测试。对于非程序员出身的博主我这里给一套“无代码测试大法”效果依然扎实基准测试准备3个同样的任务样例分别测试“不启用skill”与“启用skill”的输出差异记录下来。如果启用了skill后输出没有任何可观测差异说明skill写得太“空”或者没有被真正加载。拦截测试故意在任务指令里加入一个与skill规则冲突的要求比如skill里规定“禁止使用Emoji”你让它“在标题加一个笑脸”看它是否遵守skill。如果它立刻就听了用户的临时要求说明skill的约束力不够强需要把规则写得更加“禁止性”。改造测试修改SKILL.md中的一条规则比如把输出格式从“Markdown表格”改成“列表”再跑同样的测试任务看输出有没有跟着改。如果改了没有效果那就要怀疑你的文件是不是根本没被读取了。这种测试方式的好处是直观不需要安装额外的依赖也不依赖复杂的单元测试工具对内容创作者和个人开发者来说足够用。4.4 调试期的“脏活”常见报错与处理办法我把自己遇到过的一些报错和对应处理记在这里供你参考“Failed to load skill”大概率是SKILL.md的frontmatter格式有问题。比如name后面少了一个冒号或者description字符串没有包在引号里。检查YAML格式即可。“Skill not found”文件名拼写错误或者目录结构不对。绝大多数工具对目录名和文件名严格区分大小写一个大小写不对就会找不到。“Duplicate skill name”本地目录里有重名的skill。清理掉多余的那个就行。“Reference file not found”SKILL.md里引用的references路径错了。这里有个新手容易踩的暗坑如果你想引用references/style_guide.md路径要写相对路径别带前导斜杠之类的绝对路径。记得有一次我搞了一个半小时愣是没找到问题最后发现是我的SKILL.md文件编码是UTF-8 with BOM某些工具对这个很敏感会直接解析失败。把文件另存为“无BOM的UTF-8”之后一切正常。这种问题文档里不会写只能靠踩。4.5 如何借助GitHub和社区快速筛选可靠skills热门词里出现“skills下载平台有哪些”“GitHub skills”相关的搜索说明很多人已经意识到官方市场之外还有更广阔的社区资源。GitHub上确实有不少收集了各种skills的仓库但质量参差不齐我筛选的时候一般看三个指标最近更新时间超过半年没更新的大概率已经和当前工具版本脱节。文档完整度一个只放了SKILL.md、连README都没有的仓库通常作者自己也没怎么用过不推荐。范例与测试记录如果作者在仓库里放了使用方法、示例输入输出甚至测试结果说明这个skill至少被跑过、是可用的。另外下载别人的skill之后强烈建议你打开SKILL.md逐字读一遍而不是直接导入。你只有理解了它的规则逻辑才能在出问题时知道怎么修也才能在后续改造它的时候不被原有规则束缚。5. 当前生态里值得关注的skills与我的使用体会这节我结合自身的实际使用聊聊现在真正让我觉得“哦原来skill还能这么玩”的方向。这几个方向分别对应几个热门搜索词“自动挖洞skills”“分镜skills”“Codex写论文的skills”“WorkBuddy skills写论文”。5.1 安全测试领域的“自动挖洞skills”规则变武器在热门词里看到“自动挖洞skills”一开始我以为是开玩笑后来发现确实有人把安全测试的步骤封装成了skill。比如一个“Web渗透测试辅助skill”它会让Agent先根据输入的URL做信息收集再检查常见入口点接着是漏洞探测最后生成一份报告。整个过程被固定成了一条流水线。这类skill的思路很有启发安全测试本质上非常依赖“流程化”和“步骤复现”而skills恰恰能把专家脑子里那套“先干什么、后干什么、什么时候停”的规则固化下来。当然我这里说的只是“辅助工具”安全测试本身就涉及授权边界而且不同工具、不同平台的漏洞检测方式差异很大永远不能拿一个skill替代实际经验更不能拿它去做任何未经授权的操作。5.2 内容创作领域的“分镜skills”把经验变成框架另一个让我眼前一亮的是“分镜skills”。做短视频的都知道分镜脚本是个体力活尤其是多机位、多产品线的视频分镜质量直接决定后期效率。有人写了一个分镜skill里面定义了镜头序号、景别、画面描述、台词、时长、备注这样的结构化字段然后要求Agent按“产品卖点拆解 → 场景设定 → 镜头推进 → 口播文案”的顺序生成分镜表。我曾经在一次快闪视频项目中试过类似的分镜skill效果超出我的预期。因为没有skill的时候让Agent生成分镜它往往只是“先干什么再干什么”的相对模糊描述而加载skill之后它能直接输出一张严丝合缝的表格连画面切换的转场方式都给你。这就是“把个人经验变成可复用框架”的最典型例子。5.3 论文写作方向从“帮我写”到“教我改”热门词里“codex写论文的skills”“workbuddy skills 写论文”“reasonix如何安装新skills”这几个词扎堆出现说明论文写作是很多人最关心的场景。我自己也用Codex配合论文类skill处理过文献综述和结构优化体验确实和裸用Agent完全不同。裸用Agent时你让它“润色这一段引言”它可能会给你改得字句通顺但段落整体的逻辑推进方向可能你没有掌控感。而加载了论文写作skill之后Agent会先检查这段引言的“背景→研究缺口→本文工作”三段式是否完整再决定是“补充背景信息”还是“压缩综述长度”最后才动笔改。这一个“先诊断、后修改”的过程其实是论文评审的基本功一旦封装成skillAgent就像被注入了一位审稿人的思维方式。我特别想提醒的是这类skill的价值不是“帮你把论文从0到1写出来”而是“在你已有的基础上帮你做结构化的诊断和优化”。指望Agent凭空产出一篇高质量论文的人大概率是要失望的因为论文的核心还是你的研究工作和逻辑思考。skill能优化的只是“表达与组织”这一层的质量。5.4 从“单个skill”到“技能栈”组合使用才是终极形态聊到这里你应该发现了单个skill解决单个场景而真正让Agent升级的是“技能栈”的组合。我自己现在常用的组合是规划型skill接到复杂需求时先激活它让Agent列出执行计划。领域辅助skill根据任务类型加载不同的专业知识包比如写作规范、代码风格指南。审查型skill任务完成后跑一遍检查结构、字数、风格是否达标。工具调用skill把“需要执行外部脚本或搜索”的请求转给具体工具。这几个skill之间不是独立的它们之间有“接力关系”前一个skill的输出会成为后一个skill的输入。规划型skill生成的提纲传到领域辅助skill手里变成“按这个提纲写”写完的内容再传给审查型skill“按这个清单检查”。整个链路过一遍你会觉得Agent像是一个被SOP武装过的项目经理而不是一个单点工具。我踩了这么多坑之后最大的体会是skills的真正价值不在于“技能数量”的堆叠而在于它帮你把“所有可复用的思考过程”从一次性的对话中解放出来。那些你反反复复、不厌其烦跟Agent重复的规则、流程和标准本来就该被固定下来。你只需要维护好这一份“知识资产”之后每一次调用都是在替未来的你省时间。如果你也想试试我的建议是不要一开始就搞一堆花哨的skill先用一周时间观察自己日常使用Agent的场景挑出那个你反复需要“叮嘱一遍”的任务把它做成你的第一个skill。它可能只有50行也可能不需要任何脚本但只要它真能让你少重复一次说明它就值了。