1. 先说清楚skills到底是什么最近skills这个词在AI开发圈里突然就炸了前端开发skills、agent skills测试、codex skills、superpower skills这些关键词满天飞。如果你还没搞明白它和普通的prompt、插件、MCP有什么区别那这篇文章可以帮你一次理清楚。简单说AI Agent的skills技能本质上是一组可复用的能力包——一个文件夹里装着指令文档、脚本和资源文件让AI助手Claude、Codex这类Agent在面对特定任务时能够按照预定义的高质量流程去执行。它解决的是一个很实际的问题每次让AI干活都要重复调教一遍太痛苦了为什么不能像给员工写SOP一样把一套成熟的工作方法打包给AI这玩意儿最打动我的一点是它的文档驱动设计哲学。一个skill的核心是一份带格式约定的Markdown文件叫做SKILL.md模型通过读这个文档来理解遇到这类任务你该按什么步骤来、你要调用哪些脚本、你要输出什么格式。也就是说你不需要写一大堆复杂的插件代码用自然语言把流程描述清楚AI就能照做。这篇文章适合谁看适合已经在用Claude、Codex等Agent工具、但觉得默认行为不够可控、想让AI真正专业化的开发者也适合刚听说skills这个概念、想入门的小白。我会从原理讲到实操再讲到踩坑尽量让你看完就能自己上手。2. 拆开一个skill看看目录结构、SKILL.md和运行机制2.1 SKILL.md是灵魂YAML头信息加Markdown正文一个标准的skill目录长这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── fetch_data.py │ └── parse_results.js └── assets/ └── templates/SKILL.md是整个skill的核心入口它由两部分组成开头的YAML frontmatter和正文。frontmatter里最重要的两个字段是name技能名和description技能描述。别小看这个descriptionAgent判断当前任务该不该用这个skill靠的就是它——系统会把当前任务和所有已安装skill的描述做语义匹配匹配度高了才会自动触发。正文部分则是真正的操作手册。你要告诉模型这个技能是干什么的、应用的边界是什么、执行时遵循哪些步骤、有哪些注意事项、输出格式长什么样、需要调用哪些脚本、脚本的参数怎么传。写得越结构化、越具体模型执行得就越稳定。我见到过很多失败的skill问题几乎都出在正文太笼统。你在SKILL.md里写的不是给搜索引擎看的摘要而是给模型看的操作SOP——它没有隐性常识不会自动脑补你的意图你必须把关键约束明确写出来。比如你做一个写周报的skill你不能只写生成一份周报你得写清楚汇报对象的层级、需要包含哪几个板块工作进展/问题风险/下周计划、每个板块的字数范围、用什么样的语气、要不要附数据表格。2.2 脚本与资源真正干活的引擎SKILL.md负责告诉模型怎么做而scripts目录里的脚本负责把事情真的做掉。这其实是skills设计里非常聪明的一环纯文档适合描述流程和规范但一旦涉及批量文件操作、调用外部API、处理结构化数据让模型对着文档手写临时代码既慢又容易出错。有配套脚本模型只需要按SKILL.md里的说明去执行命令、传参数可靠性大幅提升。举个例子我自己写过一个批量压缩图片的skill。SKILL.md里只写了压缩策略和参数约定实际压缩逻辑放在scripts/compress.py里。模型接到任务后调用脚本、传入目标目录和压缩比脚本自己遍历文件、批量处理、输出报告。整个过程模型的角色从程序员变成了操作员出错率自然就降下来了。assets目录通常放模板、样例、配置文件这类静态资源。比如论文写作skill可以放一个论文结构模板.md分镜skill可以放几个分镜表范例。模型在执行时可以直接读取这些文件作为参考输出质量会更稳定。2.3 为什么是文档驱动而不是代码驱动这可能是skills最反直觉也最值得理解的设计。传统我们习惯了一切皆代码——功能要用代码实现逻辑要用代码表达。但skills选择让Markdown文档当主角有几个很实际的原因。第一是门槛低。写一个能用的小skill本质上就是写一份条理清晰的操作说明不需要会编译、不需要处理依赖关系、不需要考虑跨平台。这会带来生态的爆发式增长事实也确实如此——GitHub上已经出现了大量个人开发者贡献的skill合集像superpowers这种打包了几十个技能的能力集一个人就能维护得动。第二是AI友好的表达形式。大模型本身就是靠自然语言训练的一份写得很好的SKILL.md对模型来说是最高效的输入。代码当然也重要但代码的抽象层次和模型的思考方式不一定吻合。文档则能直接把为什么这么做什么时候该停什么情况要检查这类上下文传递给模型这是纯代码很难做到的。第三是审计和演化更自然。skill的改动可以像文档一样diff、review、版本化。团队里任何人想改进某个skill直接编辑一段文字就好了不需要理解复杂的插件SDK。这种把能力沉淀成文档的思路其实和优秀团队维护内部wiki的精神一脉相承——只不过这次的读者是AI。3. 把现成的skills装进Agent安装与调用实操3.1 去哪儿找靠谱的skills官方市场与社区渠道现在skills的获取渠道已经很丰富了。Claude官方有内置的市场可以直接在客户端里浏览、一键安装社区贡献的skill。想要更广的覆盖面可以去GitHub搜awesome-claude-skills这类汇总仓库或者直接看一些star数高的合集项目——superpowers就是目前非常活跃的一个skill集作者是Jesse Vincent里面收录了几十个经过验证的技能覆盖面从写作辅助到代码审查都有。社区搜索时我有个判断标准别只看star数要看SKILL.md的写法。写法敷衍、正文只有三行帮我做XXX的skill装进去大概率是在浪费上下文空间。好的skillSKILL.md正文通常有明确的执行流程、边界条件和输出规范scripts目录里还有配套脚本。这就跟挑开源项目一样看文档质量比看宣传语靠谱得多。3.2 安装到对应目录Claude与Codex的差异装skill的方式取决于你用的是哪个Agent。以Claude为例个人skills安装在~/.claude/skills/目录下把整个skill文件夹丢进去就行重启会话后新skill就会被识别。Codex这边类似也是把skills放到对应的工作区目录或全局目录具体路径在官方文档里写得很清楚装的时候注意区分全局和项目级——全局skills对所有会话生效项目级skills只在当前仓库内生效。这里有个实操细节值得说目录名就是skill的名字。你创建~/.claude/skills/my-report-writer/那么这个skill的标识就是my-report-writer。给目录起名时要用短横线分隔的小写英文字母别用中文、别带空格不然匹配逻辑很容易出问题。3.3 调用方式自动匹配与手动触发skill的触发逻辑有两种。第一种是自动匹配——你直接给Agent一个任务它根据任务内容比对skill描述觉得合适就会自动加载使用。第二种是手动触发——你在对话里显式提到skill名比如用write-report这个skill生成一下季度总结。我实测下来自动匹配在简单场景下表现不错但复杂任务里经常出现该用的时候没用、不该用的时候乱用的情况。所以我的建议是关键任务务必手动点名。在需要严格复现流程的场景里明确说出skill名字让模型知道现在你必须按这个流程走这比寄希望于模型的自我判断要稳得多。如果Agent支持通过命令行方式操作skill也可以写进工作流里确保每次执行都被固定下来。4. 自己写一个skill从需求到落地的完整流程4.1 需求拆解什么样的能力适合做成skill先说结论凡是你反复让AI做、流程相对固定、期望输出有统一标准的事都适合做成skill。比如日常周报汇总、图片批量压缩、竞品信息收集、代码仓库规范检查——这些任务重复度高、规则明确沉淀成skill能省掉大量重复沟通。不适合做成skill的也有一次性创意任务、需要实时交互的对话、决策路径极不稳定的任务。这种场景硬做成skill要么指令写得过于宽泛导致没有约束力要么为了覆盖所有分支把SKILL.md写得比字典还厚模型反而抓不住重点。项目启动前我习惯先花十分钟回答三个问题这个任务的输入和输出分别是什么中间有几条必经的子步骤哪几个环节最容易出错把答案写下来SKILL.md的骨架基本就出来了。4.2 撰写SKILL.md让模型看得懂你的意图写SKILL.md有几个反复验证过的原则。第一前30行就要说清楚这个skill干什么和不干什么。模型读文档是有注意力权重的越靠前的信息越容易被采纳。把边界条件写在前头能有效防止模型越界发挥。第二步骤编号化。用清晰有序的Step 1、Step 2、Step 3把执行流程列出来。有实验数据显示编号化的步骤比自由段落式的描述执行一致性高很多。每个步骤里再注明当出现XXX情况时做YYY相当于给模型预置了异常处理分支。第三输出模板化。与其用文字描述输出要好看一点不如直接在SKILL.md里嵌入一个输出模板规定标题层级、段落结构、字段名称。模型照着模板填空产出的结果稳定到你怀疑人生。第四明确哪些事模型可以自主决定哪些必须询问用户。比如生成周报时如果缺少上周数据必须向用户询问来源不得自行编造。这类授权边界写清楚能避免很多灾难性输出。4.3 测试与迭代skill也要版本管理写好的skill一定要经过多轮测试再投入使用。我最常用的测试方式准备3到5个典型任务样例在干净会话里分别触发这个skill逐个检查输出是否按SKILL.md的约束执行。如果某个步骤模型总是跳过别觉得是模型笨大概率是你的指令有歧义或者上下文顺序有问题——调整措辞让关键动作更显眼再跑一轮。我自己维护的skill现在都会做版本管理。每次修改SKILL.md后我会在frontmatter里加一个version字段在正文末尾用change log记录本次改了什么。这样一旦新版本出了问题还能快速回退到旧的稳定版本。对于团队协作的使用场景建议直接把skills目录纳入git仓库所有变更走代码评审流程——你会发现review一份SKILL.md的改动比review一段代码的改动成本低得多。5. 常见问题与排查技巧实录5.1 skill没生效名字、路径、触发词的坑这是新手最容易卡住的一关。装了好几个skill结果对话里提了半天模型完全没反应。排查顺序通常是先确认目录放在了正确的位置、目录名符合规范再检查SKILL.md开头的frontmatter是不是被解析成功——YAML缩进错误、多了一个非法字段都可能导致整个skill被跳过最后看description写得好不好如果描述和任务的语义距离太远模型根本不会匹配到这个skill。还有一个不容易发现的坑修改SKILL.md后没有重启会话。很多Agent在会话启动时才扫描一次skills目录你中途改了文件当前会话里用的还是旧版本。我踩过好几次这个坑改了半天参数发现行为完全没变最后重启会话一切正常。5.2 模型不按SKILL.md执行指令设计的常见误区Skill装了、触发了但模型的执行结果和SKILL.md里描述的大相径庭。这种问题九成出在指令设计上。最常见的误区是一次性塞太多内容——SKILL.md超过300行模型读着读着就迷失了。解决办法是拆分把详细步骤、脚本说明挪到SKILL.md同目录下的辅助文档里比如REFERENCE.md正文里只留必要流程需要时引导模型自己去看辅助文档。第二个误区是约束分散在长文的各个角落。模型不是逐字读文档的它的注意力会集中在开头和结尾。把最重要的约束放在显眼位置用必须禁止不要这类强指令词重复强调也不过分。我写skill的惯例是核心约束至少出现两次——前排概述里一次对应步骤里再具体展开一次。5.3 多skill冲突与优先级能力池的管理策略安装的skill一多新的问题出现了任务描述模糊时Agent可能同时匹配到两三个skill或者一个都匹配不上。面对这种情况我建议你在description里明确写清楚适用场景和不适用场景。你甚至可以故意在描述里写如果任务不满足XXX条件请勿使用本skill这能有效压缩误匹配的概率。如果多个skill确实存在功能重叠一个是通用版一个是特定场景加强版我会在场景加强版的描述里直接写当用户明确提到XXX时优先于通用版使用。实测下来这种显式的优先级声明比指望模型自己比较两个skill的适用范围要可靠得多。另一个管理策略是控制并发生效的skill数量。很多Agent会一次性把匹配到的所有skill都注入上下文skill多了不但消耗上下文窗口还会让模型决策变慢。我自己会把常用skill控制在10个以内不常用的临时放到备份目录需要时再启用。这个习惯让会话的整体响应速度和执行质量都有明显提升。6. 一些经验体会和后续扩展方向用skills这套机制折腾了这么久我最大的感受是它真正把AI能力复用这件事的门槛降了下来。以前写插件要懂SDK、要处理依赖、要考虑兼容性现在写好一份文档AI就能按你的标准干活。这种授人以SOP的思路对整个工具生态的影响才刚刚开始。最后分享两个小建议。一是别急着一次装一堆skill先从自己最高频、最消耗精力的任务入手做一个跑通全流程吃透机制后再批量扩展。二是skill的迭代依赖真实使用反馈每次用完不满意花五分钟把模型哪里没按规范做记下来集中改进SKILL.md——坚持几轮之后你的skill会比市面上的大多数通用skill好用得多。后续值得关注的方向我个人比较看好两个一个是带复杂脚本链的skill让模型不仅能写文档、还能编排多步骤自动化任务另一个是团队级skill库的共享与沉淀机制一套优质的技能库可能会成为团队在AI时代的重要资产。你现在开始积累的每一个skill都在为这个方向打下基础。