1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题很多人会一头雾水。它既不是某个具体软件的名字也不是一个能一眼看懂的技术名词。但如果你最近在折腾 Claude Code、Codex 这类 AI 编程助手或者关注过 Agent 生态的动向就会发现skills已经成了一个绕不开的概念。简单说skills 是一套让 AI 助手获得特定领域能力的模块化技能包它通过一个叫SKILL.md的约定文件来描述这个技能能做什么、什么时候触发、怎么执行。我最初接触这个概念时以为它不过是又一个提示词模板的包装。真正上手之后才意识到skills 的设计思路和传统的 prompt 工程有本质区别。传统提示词是你每次对话都要重新交代背景而 skills 是一次定义、按需加载——AI 助手在遇到匹配的任务时会自动读取对应的SKILL.md按照里面写好的流程和规范来干活。这就好比以前你每次找人帮忙都要从头解释一遍需求现在你给每个帮手发了一本操作手册他遇到对应场景自己翻手册就行。这套机制解决的核心痛点是上下文膨胀和知识复用。一个复杂的项目往往涉及前端构建、数据库迁移、接口测试、文档生成等十几个环节如果把这些全部塞进系统提示词token 消耗惊人而且模型注意力会被稀释。skills 把这些能力拆成独立模块用到哪个加载哪个既省 token 又提高准确率。对于经常用 Claude Code 做开发的人来说掌握 skills 的编写和安装基本等于给自己的 AI 助手装上了一套可扩展的技能库。这篇文章适合三类人一是刚接触 Claude Code、还在摸索怎么让它更好用的新手二是想把自己团队的规范沉淀成可复用技能包的开发者三是好奇 Agent Skills 底层机制、想搞清楚SKILL.md到底怎么写的技术爱好者。下面我会从概念、结构、编写、安装、排错到实战场景把 skills 这套东西彻底讲透。2. SKILL.md 的解剖一个技能包由哪些零件组成2.1 目录结构为什么是文件夹而不是单个文件很多人第一次下载 skills 时会疑惑为什么不是一个.md文件而是一个文件夹这背后有实际考虑。一个完整的 skill 通常包含三部分元数据描述、执行指令、辅助资源。元数据要告诉 AI我是谁、我什么时候该被激活执行指令是具体的操作步骤辅助资源可能是脚本、模板、参考文档。如果全塞进一个文件既不好维护也没法携带二进制资源。典型的 skill 目录长这样my-skill/ ├── SKILL.md # 核心描述文件必须有 ├── scripts/ # 可选的辅助脚本 │ └── build.sh ├── templates/ # 可选的模板文件 │ └── component.tsx └── references/ # 可选的参考资料 └── api-spec.mdSKILL.md是唯一强制存在的文件其他目录都是按需添加。我见过有人把所有东西都写进SKILL.md结果文件超过两千行AI 读取时反而抓不住重点。合理的做法是让SKILL.md保持精简把大段参考资料拆到references/里需要时再引用。2.2 元数据字段name 和 description 的门道SKILL.md开头是一段 YAML 格式的元数据用三条横线包裹。最关键的字段是name和description--- name: react-component-generator description: 当用户需要创建 React 函数组件、涉及 useState/useEffect 或需要组件测试文件时使用。生成符合项目 ESLint 规范的 TypeScript 组件。 ---name要求小写字母加连字符长度有限制它是技能的唯一标识。description才是真正决定技能能否被正确触发的关键。我踩过的坑是一开始把 description 写得太笼统比如帮助处理前端任务结果 AI 几乎从不主动加载它因为描述太模糊匹配不上具体场景。后来我改成**触发条件 能力范围 输出约束**三段式写法命中率立刻上来了。触发条件要写清楚当用户做什么时使用能力范围说明能完成什么输出约束交代遵循什么规范。这三样缺一不可。实测下来description 里包含具体的技术名词如 React、TypeScript、ESLint比抽象描述有效得多因为 AI 是靠语义匹配来判断是否加载的。2.3 正文指令写给 AI 看的操作手册元数据下面是正文也就是 Markdown 格式的指令内容。这部分是给 AI 读的所以写法要和写给人看的文档区分开。我的经验是遵循几个原则用祈使句不用描述句。写检查 package.json 中是否已有该依赖而不是package.json 中通常会有依赖列表。步骤要可执行、可验证。每一步都应该是 AI 能直接动手做的动作而不是需要它自己揣摩的模糊要求。明确边界和例外。告诉 AI 什么情况下不要用这个技能比告诉它什么时候用同样重要。一个常见的错误是把SKILL.md写成教程。教程是给人学习用的而SKILL.md是给 AI 执行用的。AI 不需要知道为什么 React 要用函数组件它只需要知道生成组件时使用函数式写法不用 class。把背景知识砍掉只留可执行指令这是我反复调试后总结出的最重要一条。3. 手写第一个 skill从前端组件生成器开始3.1 需求拆解先想清楚要解决什么重复劳动动手写之前先问自己一个问题我平时用 AI 助手时哪类任务反复交代同样的要求对我来说是生成 React 组件。每次都要说用 TypeScript、用函数组件、样式用 CSS Modules、要写 PropTypes 或者类型定义、测试文件用 React Testing Library。说一遍两遍还行说二十遍就烦了。这就是一个典型的适合做成 skill 的场景。选这个作为第一个 skill 还有个好处它的输入输出都很明确容易验证效果。你写完SKILL.md后直接让 AI 生成一个组件看它是否遵循了你定的规范一目了然。相比之下像代码审查这种主观性强的技能验证起来就麻烦得多。3.2 编写 SKILL.md把口头要求翻译成结构化指令下面是我实际在用的组件生成器 skill 的核心内容做了简化--- name: react-component-generator description: 当用户要求创建新的 React 组件、生成组件骨架或需要配套测试文件时使用。输出 TypeScript 函数组件遵循项目现有目录约定。 --- # React 组件生成器 ## 执行步骤 1. 确认组件名称转换为 PascalCase 作为文件名和组件名。 2. 检查项目是否使用 TypeScript。若 tsconfig.json 存在生成 .tsx 文件否则生成 .jsx。 3. 按以下模板生成组件 - 使用函数声明不用箭头函数赋给变量。 - Props 用 interface 定义命名格式为 {组件名}Props。 - 样式优先使用项目已有的方案检查是否安装 styled-components、CSS Modules 等。 4. 若用户要求测试生成同名 .test.tsx 文件使用 React Testing Library。 5. 生成后运行 npx tsc --noEmit 验证类型若有错误则修正。 ## 禁止事项 - 不要生成 class 组件。 - 不要引入未在 package.json 中声明的依赖。 - 不要添加未要求的注释和文档字符串。这份文件不到四十行但把关键约束都覆盖了。注意第 2 步和第 5 步——让 AI 先探测环境再动手生成后自己验证这两步是让技能真正可用的关键。很多新手写的 skill 只描述生成什么不描述怎么确认生成对了结果 AI 产出看似合理但实际跑不起来的代码。3.3 本地测试怎么判断 skill 有没有生效写完之后怎么测我的流程是这样的先把 skill 文件夹放到 Claude Code 能识别的 skills 目录下不同版本路径可能不同通常在用户配置目录的skills/子目录然后重启会话输入一个触发性的请求比如帮我创建一个 UserCard 组件。判断是否生效有两个信号一是 AI 的回复里会体现出它读取了 skill 的指令比如主动检查 tsconfig、主动运行类型检查二是如果 skill 里有明确的禁止事项AI 会遵守。如果 AI 完全没反应八成是 description 没匹配上或者文件路径放错了。提示调试 skill 时可以临时在 description 里加上非常具体的关键词确认能被触发后再逐步改回自然的表述。这比反复猜测匹配逻辑高效得多。我遇到过一个坑skill 写好了但死活不触发排查半天发现是 YAML 元数据的缩进用了 Tab 而不是空格。YAML 对缩进极其敏感统一用两个空格这是血泪教训。4. 安装第三方 skills路径、依赖与常见报错4.1 从 GitHub 获取 skill 的正确姿势社区里已经有不少人分享了自己写的 skills从数学建模到 AI 漫剧生成从 STM32 开发到代码清理覆盖面很广。从 GitHub 获取 skill 的流程一般是找到仓库克隆或下载然后把 skill 文件夹放到本地 skills 目录。这里有个容易忽略的点很多 skill 仓库是整个项目仓库skills 藏在子目录里。你不能把整个仓库扔进 skills 目录而要找到真正包含SKILL.md的那一层文件夹。我见过有人把带.git的整个仓库复制进去结果 AI 扫描时被无关文件干扰技能反而不触发。正确的做法是下载后先找SKILL.md文件它所在的文件夹才是要安装的 skill。如果仓库里有多个 skill就分别复制每个包含SKILL.md的文件夹。4.2 依赖处理skill 里引用的脚本和工具有些 skill 不只是纯文本指令还带了脚本。比如一个批量重命名文件的 skill 可能附带一个 Python 脚本。这类 skill 安装后要确认脚本的执行权限和运行环境。在类 Unix 系统上脚本需要可执行权限chmod x scripts/rename.sh在 Windows 上则要注意脚本的换行符问题。我有次在 Windows 上用一个带 shell 脚本的 skill怎么都不工作最后发现是脚本用了 LF 换行而系统期望 CRLF或者反过来。跨平台使用带脚本的 skill 时先确认脚本能在你的系统上独立跑通再让 AI 去调用它。另外如果 skill 依赖某个命令行工具比如jq、ripgrep要提前装好。AI 执行到那一步发现命令不存在整个流程就断了。稳妥的做法是在SKILL.md里让 AI 先检查依赖是否存在不存在就提示用户安装。4.3 常见报错对照表下面这张表是我和身边朋友踩过的坑汇总基本覆盖了新手会遇到的绝大多数问题报错或现象根本原因解决方式skill 完全不触发description 太笼统或路径错误检查文件夹是否含 SKILL.mddescription 加具体技术词YAML 解析失败缩进用了 Tab 或冒号后缺空格统一两个空格缩进冒号后加空格脚本执行报权限错误脚本无可执行权限chmod x或改用解释器显式调用命令找不到依赖工具未安装安装对应 CLI 工具或在 skill 里加检查步骤技能触发但行为不符预期指令有歧义或缺少验证步骤把模糊表述改成可执行动作增加自检环节多个 skill 冲突触发条件重叠收窄各自 description 的适用范围这张表里的每一条背后都是真实浪费过的时间。尤其是最后一条当你装了一堆 skill 后两个技能的触发条件如果都写得很宽泛AI 可能加载了错误的那个。给每个 skill 划定清晰的职责边界比追求功能大而全更重要。5. 让 skill 真正好用的几个设计原则5.1 单一职责一个 skill 只干一件事我最初写 skill 时贪多想做一个全能前端助手结果里面塞了组件生成、样式处理、路由配置、状态管理四大块。用起来发现AI 每次加载这个 skill 都要读一大堆它当前用不上的内容反而降低了针对性。后来我把它拆成四个独立 skill每个都短小精悍触发准确率和执行质量都明显提升。这背后的道理和函数设计一样单一职责的模块更容易被正确调用。skill 的加载是有成本的消耗上下文一个 skill 越聚焦AI 判断该不该用它就越容易用起来也越精准。5.2 渐进式披露别一次性把所有细节倒出来Claude 官方在讲 Agent Skills 时提到一个概念叫渐进式披露progressive disclosure。意思是SKILL.md主体只放最核心的流程详细的参考资料放在references/目录等 AI 真正需要时再去读。举个例子一个API 对接skill主体只写根据接口文档生成请求函数遵循项目现有的 fetch 封装然后把完整的接口规范放在references/api-spec.md。这样 AI 在判断是否加载这个 skill 时只需要读简短的 description真正执行时才按需读取详细规范。这个设计能显著降低上下文占用尤其在 skill 数量多的时候效果明显。5.3 可验证性让 AI 能自己检查做对了没有这是区分玩具 skill和生产级 skill的分水岭。好的 skill 会在关键步骤后安排验证动作。比如生成代码后运行类型检查、生成配置后校验 JSON 格式、修改文件后确认改动符合预期。我在写数据库迁移 skill 时特意加了一步生成迁移脚本后先在本地测试库跑一遍确认能成功执行再交付。这一步让 skill 的可靠性提升了一个档次——AI 不再是生成完就交差而是生成完自己验证过。当然这要求你在SKILL.md里明确写出验证命令和判断标准。5.4 版本管理skill 也需要迭代skill 不是写完就一劳永逸的。项目规范变了、依赖升级了、发现新的边界情况了都要回头改SKILL.md。我的习惯是给每个 skill 文件夹里放一个CHANGELOG.md记录每次修改的原因。这样过几个月回头看能快速回忆起当初为什么那么写。如果团队多人共用 skill建议把 skill 仓库纳入版本控制像管理代码一样管理它。skill 本质上是团队知识的代码化沉淀值得用工程化的方式对待。6. 实战场景skills 在不同领域的落地方式6.1 数学建模把建模流程标准化数学建模比赛里时间紧、任务重很多重复性的工作可以交给 skill。比如数据预处理 skill可以固化读入数据、检查缺失值、标准化、划分训练测试集这一套流程论文排版 skill 可以固化格式要求。我了解到有参赛者把常用的几种模型线性回归、时间序列、优化模型各做成一个 skill比赛时直接调用省下大量查文档和调参的时间。这类 skill 的关键是把经验判断转成条件分支。比如数据量小于一千用交叉验证大于一万用留出法这种规则写进 skillAI 就能按你的经验来决策而不是每次随机选一种。6.2 前端开发规范落地不再靠嘴说前端团队最头疼的问题之一是代码风格不统一。ESLint 能管一部分但组件怎么写、目录怎么组织、状态放哪里这些约定很难靠工具强制。把这些写进 skillAI 生成的代码天然符合团队规范新人也能通过 skill 快速理解项目约定。我见过一个团队把新增页面的完整流程做成了 skill从创建目录、生成组件、配置路由到写测试一条龙。新人接手时只要触发这个 skill产出的代码结构和老手写的一模一样。这比写十页文档都管用因为文档没人看skill 是直接参与生产的。6.3 内容创作AI 漫剧与文案生成热词里提到AI 漫剧常用 skills这其实是个很有意思的方向。漫剧创作涉及分镜、台词、画面描述、配音脚本等多个环节每个环节的产出格式都有讲究。把这些环节做成 skill创作者只需要提供故事梗概AI 就能按既定格式产出分镜脚本和画面提示词。这类 skill 的设计要点是输出格式的强约束。因为下游工具比如图像生成对提示词的格式很敏感skill 里必须明确规定输出的结构不能有自由发挥的空间。我建议在这类 skill 里附上几个标准输出样例让 AI 照着样例的格式来。6.4 嵌入式与硬件STM32 开发的辅助有热词提到claude code stm32说明有人在用 AI 助手做嵌入式开发。嵌入式开发的痛点是寄存器配置、外设初始化这些样板代码多且容易出错。一个 STM32 skill 可以固化根据外设需求生成初始化代码、检查时钟配置、生成中断处理框架的流程。这类 skill 要特别注意硬件相关的约束。比如某个引脚已经被占用、某个时钟源频率固定这些约束要写进 skill否则 AI 生成的配置可能和实际硬件冲突。把硬件手册里的关键约束提炼成 skill 里的检查项是这类技能的核心价值。7. 排查 skill 不生效的完整思路7.1 第一步确认文件被正确识别skill 不工作时先别急着改内容从最外层查起。确认三件事文件夹里有没有SKILL.md、文件名的拼写和大小写对不对、文件夹放的位置是不是 AI 助手扫描的目录。不同工具、不同版本的 skills 目录位置不一样有的在用户主目录下的配置文件夹有的在项目根目录。先查文档确认路径再动手。我一般会用一个最小可触发 skill来测试环境写一个 description 里包含测试触发字样的 skill然后输入测试触发看 AI 有没有反应。这一步能快速区分是环境问题还是内容问题。7.2 第二步检查 YAML 元数据格式如果文件被识别了但技能不触发八成是元数据的问题。YAML 格式对新手很不友好几个高频错误冒号后面没加空格、缩进混用了 Tab 和空格、字符串里包含了特殊字符没加引号。把元数据单独复制到一个 YAML 校验工具里验证一下能省下大量排查时间。还有一个隐蔽的坑description 太长被截断。有些工具对 description 长度有限制超出的部分会被忽略导致触发条件不完整。如果描述确实需要很长把核心触发词放在最前面。7.3 第三步验证指令的可执行性技能触发了但行为不对问题就在正文指令。这时候要逐条检查每条指令是不是 AI 能直接执行的有没有需要它猜的地方验证步骤是否明确我的排查方法是把SKILL.md的指令当成给一个新人的任务清单逐条问自己这句话有没有歧义。比如生成合适的样式就是有歧义的什么叫合适改成使用项目已有的 CSS Modules类名用 camelCase就明确了。模糊的指令是 skill 失效的头号原因比格式错误更常见。7.4 第四步观察 AI 的实际执行路径如果前三步都没问题就要看 AI 到底怎么执行的了。在 Claude Code 这类工具里通常能看到 AI 读取了哪些文件、执行了哪些命令。观察它的实际路径往往能发现你没想到的问题比如它跳过了某个步骤、误解了某个条件、或者被其他 skill 干扰了。我遇到过一次AI 总是跳过验证步骤。查了半天发现是另一个 skill 的指令里写了尽快给出结果两个 skill 同时加载时产生了冲突。skill 之间会相互影响装得多了要留意这种隐性冲突。8. 关于 skills 的一些个人体会用了一段时间 skills 之后我最大的感受是它改变的不是 AI 的能力上限而是 AI 的稳定性下限。同一个模型没有 skill 时表现时好时坏全看你怎么提问有了精心设计的 skill它在特定任务上的表现就稳定在一个可预期的水平。这对需要重复产出、要求一致性的工作场景价值巨大。另一个体会是写 skill 的过程其实是逼自己把隐性知识显性化。很多老手做事情靠的是直觉和经验这些很难传授。但写 skill 时你必须把我为什么这么做拆解成一条条明确的规则这个过程本身就是对自身经验的梳理。我写完几个 skill 后发现自己对某些流程的理解反而更清晰了。最后分享一个小技巧从最小的 skill 开始别一上来就追求完美。先写一个只包含三五行指令的 skill跑通、验证、再逐步加内容。我见过太多人想一次写出一个终极技能包结果卡在调试环节就放弃了。skill 是迭代出来的不是设计出来的。先让它能用再让它好用这个顺序不能反。