1. 从skills这个热词说起它到底在解决什么问题最近一段时间不管是在技术社区还是开发者群聊里skills这个词出现的频率高得离谱。很多人第一次看到它会以为是某种新的编程语言或者框架其实不是。这里的 skills指的是围绕 AI 编程助手比如 Claude Code、Codex 这类工具构建的一套可复用的能力模块。你可以把它理解成给 AI 助手装的技能包——装上一个 skillAI 就多会一件事装上一套 skillsAI 就能从能聊天变成能干活。我最初接触这个概念的时候也是懵的。因为网上关于 skills 的资料非常零散有人说是插件有人说是提示词模板还有人说是某种配置文件。实际上skills 的本质更接近于结构化的任务指令集它把某个具体场景下的操作流程、注意事项、输出格式全部封装好AI 助手在需要的时候自动加载然后按照预设的方式完成任务。这跟传统的每次都要重新写一遍提示词相比效率提升是数量级的。为什么 skills 会突然火起来核心原因在于大家发现通用大模型虽然聪明但在具体任务上经常不听话——你让它写代码它给你写一堆注释你让它改 bug它把整个文件重写一遍。skills 的出现就是给这种不听话套上一个约束框架让 AI 在特定任务上表现得像一个训练有素的专才而不是一个什么都懂一点但什么都不精的通才。这篇文章适合谁看如果你是刚接触 Claude Code 或 Codex 的新手想搞清楚 skills 到底是什么、怎么装、怎么用那这篇内容能帮你少走很多弯路。如果你已经用过一段时间但总觉得效果不稳定那这里面关于 skill 设计思路和踩坑经验的部分应该对你有参考价值。我不会讲太多虚的概念重点放在实际怎么操作、为什么这么操作、以及我踩过的那些坑上。2. skills 的核心机制它凭什么能让 AI 变听话2.1 skill 不是插件但它比插件更轻很多人第一次听到 skills会下意识地把它和 VS Code 插件、IDEA 插件类比。这个类比有一半是对的但另一半会误导你。相同的地方在于它们都是扩展能力的手段不同的地方在于插件通常是二进制程序需要安装、编译、加载而 skill 本质上就是一组文本文件通常是 Markdown 或者 YAML 格式里面写清楚了什么时候用这个 skill用的时候要做什么输出要长什么样。这意味着什么意味着你可以用记事本打开一个 skill直接改里面的内容改完保存AI 下次调用的时候就会用你改过的版本。这种可读可改的特性是 skills 相比传统插件最大的优势。我见过不少团队把内部代码规范、部署流程、甚至代码审查清单全部写成了 skill新来的同事只要装上这套 skillsAI 助手就会按照团队的标准来干活省去了大量口头培训的成本。从技术实现上看skill 的加载机制通常是这样的AI 助手在启动或者执行任务时会扫描指定的 skills 目录读取每个 skill 的元数据比如名称、触发条件、描述然后根据当前任务的内容判断是否需要加载某个 skill。如果需要就把 skill 的完整内容注入到上下文里让模型按照 skill 的指示来执行。这个过程对用户是透明的你不需要手动启用某个 skill只要它放在正确的位置AI 自己会判断。2.2 触发条件的设计决定了 skill 好不好用一个 skill 能不能发挥作用关键看它的触发条件设计得合不合理。触发条件写得太宽AI 会在不相关的任务上也加载这个 skill导致输出跑偏写得太窄AI 又经常想不起来用它等于白装。我举个例子。假设你写了一个生成单元测试的 skill触发条件如果只写当用户要求写测试时那 AI 在你说帮我给这个函数加个测试的时候可能会触发但在你说这个模块的覆盖率不够的时候就不会触发。更好的写法是把触发条件写成当任务涉及测试编写、覆盖率提升、测试用例补充时这样覆盖面更广AI 更容易判断出该用这个 skill。还有一个容易被忽略的点skill 的优先级。如果你装了很多 skill它们之间可能会有冲突。比如一个 skill 说输出代码时要加详细注释另一个 skill 说输出代码时要保持简洁AI 到底听谁的这时候就需要在 skill 里明确优先级或者在设计的时候就避免功能重叠。我的经验是同类功能的 skill 只保留一个不要装多个功能相似的否则 AI 会陷入选择困难输出质量反而下降。2.3 skill 的上下文注入方式影响 token 消耗skill 被加载的时候它的内容会被注入到 AI 的上下文窗口里。这意味着 skill 写得越长消耗的 token 就越多留给实际任务的空间就越少。我见过有人写了一个 3000 字的 skill结果 AI 每次执行任务都要先读完这 3000 字真正用来干活的空间被压缩得很厉害。所以写 skill 的时候要遵循一个原则能一句话说清楚的事不要写一段。比如输出代码时要遵循 PEP8 规范这一句就够了不需要把 PEP8 的每一条规则都抄进去。AI 本身就知道 PEP8 是什么你只需要告诉它要遵守就行。skill 的价值在于告诉 AI 做什么、不做什么而不是教 AI 知识。另外skill 的加载方式也有讲究。有些工具支持按需加载就是 AI 判断需要的时候才加载有些工具是全部加载启动时把所有 skill 都读进来。前者省 token但需要 AI 有较强的判断能力后者简单直接但 token 消耗大。选择哪种方式取决于你用的工具和你的实际需求。如果 skill 不多全部加载也无所谓如果 skill 很多建议用按需加载。3. 从零开始skills 的安装与配置实操3.1 环境准备不同工具的 skills 目录在哪里skills 的安装第一步是找到正确的目录。不同的 AI 编程助手skills 的存放位置不一样。我整理了一个常见的对照表你可以根据自己的工具来查工具默认 skills 目录备注Claude Code~/.claude/skills/用户级目录所有项目共享Claude Code项目级项目根目录/.claude/skills/只对当前项目生效Codex~/.codex/skills/用户级目录Codex项目级项目根目录/.codex/skills/只对当前项目生效VS Code 插件版插件设置里指定的目录需要在设置里手动配置注意如果你用的是 Windows 系统~代表的是C:\Users\你的用户名\。有些工具在 Windows 上对路径的处理不太一样建议用绝对路径避免出现找不到目录的问题。我个人的习惯是通用 skill 放在用户级目录项目相关的 skill 放在项目级目录。比如代码格式化生成注释这种走到哪都用得上的放用户级这个项目的部署流程这个项目的数据库连接方式这种只跟当前项目有关的放项目级。这样切换项目的时候不会因为加载了不相关的 skill 而干扰 AI 的判断。3.2 安装一个 skill 的完整流程假设你已经找到了 skills 目录接下来就是安装。安装一个 skill 通常有三种方式方式一手动创建。直接在 skills 目录下新建一个文件夹文件夹名就是 skill 的名字然后在里面放一个SKILL.md文件写上 skill 的内容。这是最基础的方式适合自己写 skill。方式二从市场安装。有些工具提供了 skill 市场你可以浏览、搜索、一键安装。这种方式适合新手省去了自己写的麻烦。但要注意市场里的 skill 质量参差不齐装之前最好看一下它的描述和评价。方式三从 Git 仓库克隆。很多团队会把内部的 skills 放在 Git 仓库里你只需要git clone到 skills 目录就行。这种方式适合团队协作大家用同一套 skill保证输出一致。我以手动创建为例演示一个完整的流程。假设我要创建一个生成 Git 提交信息的 skill# 进入 skills 目录 cd ~/.claude/skills/ # 创建 skill 文件夹 mkdir git-commit-helper # 创建 SKILL.md 文件 touch git-commit-helper/SKILL.md然后在SKILL.md里写入内容--- name: git-commit-helper description: 当用户需要生成 Git 提交信息时使用此 skill trigger: 用户要求写 commit message、提交代码、生成提交信息 --- # Git 提交信息生成规范 生成提交信息时遵循以下规则 1. 使用 Conventional Commits 格式type(scope): subject 2. type 可选值feat、fix、docs、style、refactor、test、chore 3. subject 使用中文不超过 50 个字符 4. 如果有必要在 body 里补充详细说明 5. 不要生成 Generated by AI 之类的字样 示例 - feat(user): 添加用户登录功能 - fix(api): 修复订单查询接口的空指针问题保存之后重启 AI 助手或者重新加载配置这个 skill 就会生效。下次你让 AI 帮你写提交信息的时候它就会按照你定义的格式来输出。3.3 验证 skill 是否生效的几种方法装完 skill 之后怎么知道它有没有生效我常用的方法有三种方法一直接问 AI。你可以问你现在加载了哪些 skill有些工具会列出当前生效的 skill 列表。如果 AI 能说出你刚装的 skill 名字说明加载成功了。方法二触发测试。故意做一个会触发 skill 的操作看 AI 的输出是否符合 skill 里定义的格式。比如你装了一个生成提交信息的 skill就随便改一行代码然后让 AI 帮你写提交信息看它是不是按照 Conventional Commits 格式来的。方法三看日志。有些工具在启动时会输出加载日志你可以在终端里看到Loaded skill: xxx之类的信息。如果日志里没有你的 skill说明路径不对或者格式有问题。提示如果 skill 没生效先检查文件格式。SKILL.md开头的---包裹的部分是元数据必须严格按照 YAML 格式写冒号后面要有空格缩进要用空格不能用 Tab。这些细节很容易出错但报错信息往往不明显。4. 写一个真正好用的 skill设计思路与实战技巧4.1 从我每次都要重复说什么出发写 skill 最实用的切入点是回想一下你每次用 AI 时都要重复交代的那些事。比如你每次让 AI 写代码都要说用 TypeScript不要用 any函数要有返回类型每次让 AI 写文档都要说用 Markdown标题不要超过三级代码块要标注语言。这些重复的话就是 skill 的素材。我把这种思路叫做重复即 skill。凡是你说过三遍以上的要求都应该考虑写成 skill。这样不仅省事还能保证每次的输出标准一致。我自己的 skills 目录里有一大半都是这么来的。具体怎么写我拿TypeScript 代码规范举例。一个基础的 skill 可以这样写--- name: typescript-standards description: 生成或修改 TypeScript 代码时使用 trigger: 任务涉及 .ts 或 .tsx 文件的编写、修改、审查 --- # TypeScript 代码规范 - 禁止使用 any不确定的类型用 unknown 或泛型 - 所有函数必须显式声明返回类型 - 优先使用 interface 定义对象结构type 用于联合类型和工具类型 - 使用 const 和 let禁止 var - 导入顺序外部库 → 内部模块 → 相对路径 - 错误处理使用 try/catch不要忽略 catch 块这个 skill 不长但覆盖了最常见的几个要求。AI 加载之后生成的代码基本就能符合团队规范不需要你每次再重复。4.2 触发条件要宽进严出前面提到触发条件的重要性这里展开说一下我的经验。触发条件的设计我总结为四个字宽进严出。宽进是指触发条件要写得宽泛一些让 AI 在更多场景下能想到用这个 skill。比如生成测试的 skill触发条件不要只写用户要求写测试而要写任务涉及测试编写、测试补充、覆盖率提升、测试重构。这样即使你没有明确说写测试AI 也能判断出当前任务跟测试有关从而加载 skill。严出是指 skill 里的执行规则要写得严格、具体。比如不要写代码要规范而要写函数名用 camelCase类名用 PascalCase常量用 UPPER_SNAKE_CASE。规则越具体AI 执行起来越不容易跑偏。我见过一个反例有人写了一个代码审查的 skill触发条件写的是当用户要求审查代码时规则写的是检查代码质量。结果 AI 要么不触发要么触发了也不知道该检查什么输出一堆代码看起来不错之类的废话。后来他把触发条件改成任务涉及代码审查、代码质量检查、PR 评审规则改成检查以下五项命名规范、错误处理、边界条件、性能隐患、安全问题效果立刻就不一样了。4.3 用示例代替描述AI 对示例的理解能力远强于对抽象描述的理解能力。你在 skill 里写十句输出要简洁不如给一个简洁输出的例子。所以我在写 skill 的时候能举例就举例。比如你要定义一个生成 API 文档的 skill与其写文档要包含接口地址、请求方法、请求参数、响应格式不如直接给一个示例# API 文档格式示例 ## 获取用户信息 - 接口地址GET /api/users/{id} - 请求参数 - id (path, required): 用户 ID - 响应示例 json { id: 1, name: 张三, email: zhangsanexample.com }AI 看到这个示例就知道你要的文档长什么样生成的时候会直接套用这个格式。这比任何抽象描述都管用。 ### 4.4 skill 的版本管理别把 skill 当一次性用品 skill 不是写完就扔的东西它需要维护。随着项目变化、团队规范调整skill 也要跟着更新。我建议把 skills 目录纳入 Git 管理每次修改都提交这样能追溯什么时候改了什么、为什么改。 另外skill 也要有版本号。在元数据里加一个 version 字段比如 version: 1.2.0。当 skill 有重大变更时升一下版本号方便团队成员知道这个 skill 更新了需要重新拉取。 我还见过一种做法把 skill 分成稳定版和实验版。稳定版放在主目录实验版放在 experimental/ 子目录。新写的 skill 先在实验版里跑一段时间验证没问题了再挪到稳定版。这种做法适合团队规模较大、skill 数量较多的情况。 ## 5. 那些年我踩过的 skills 坑 ### 5.1 skill 冲突两个 skill 打架AI 左右为难 最常见的坑就是 skill 冲突。我一开始装了很多 skill有管代码风格的有管注释的有管提交信息的。结果有一次让 AI 改代码它输出的代码既加了详细注释又保持了极简风格看起来非常别扭。后来才发现是两个 skill 的规则打架了一个说注释要详细一个说代码要简洁。 解决这个问题的办法前面提过就是**同类 skill 只保留一个**。如果你确实需要多个 skill 协作那就在 skill 里明确优先级比如在元数据里加 priority: 10数字越大优先级越高。AI 在冲突时会优先执行高优先级的 skill。 还有一种冲突是触发条件重叠。比如你有一个生成测试的 skill 和一个代码审查的 skill它们的触发条件都包含测试这个词。当你让 AI审查测试代码的时候两个 skill 都会被触发AI 就不知道该按哪个来。这时候需要把触发条件写得更精确比如生成测试的触发条件限定为编写新测试代码审查的触发条件限定为审查已有代码。 ### 5.2 skill 太长AI 读完了但没记住 前面提过 token 消耗的问题这里说一个更隐蔽的坑**skill 太长会导致 AI读了后面忘了前面**。我写过一个 2000 多字的 skill里面列了十几条规则。结果 AI 执行的时候只遵守了前几条后面的全忘了。后来我把这个 skill 拆成了三个小 skill每个只聚焦一个方面效果就好多了。 所以写 skill 的时候**单条 skill 的规则不要超过 7 条**。这是我从实践中总结出来的经验值。超过 7 条AI 的遵守率就会明显下降。如果确实有很多规则就拆成多个 skill每个 skill 管一个方面。 ### 5.3 路径问题Windows 和 Mac 的差异 跨平台使用 skills 的时候路径问题很容易踩坑。Mac 和 Linux 用 / 分隔路径Windows 用 \。有些工具在 Windows 上对 ~ 的解析也不一样。我建议在 skill 里引用文件路径时**尽量用相对路径或者环境变量**不要写死绝对路径。 还有一个坑是**文件编码**。Windows 默认可能是 GBK 编码而 skill 文件通常是 UTF-8。如果编码不对中文内容会变成乱码AI 读到的就是一堆问号。解决办法是在保存文件时明确选择 UTF-8 编码或者在 skill 里避免使用中文。 ### 5.4 更新 skill 后没生效缓存问题 有时候你改了 skill 的内容但 AI 的行为没变化。这通常是缓存问题。很多工具会把 skill 内容缓存在内存里改了文件之后需要重启工具或者手动刷新缓存才能生效。我一般的做法是改完 skill 之后先重启一次工具确认生效了再继续用。如果重启还不行就检查一下是不是有多个 skills 目录改错了地方。 注意有些工具支持热加载改了 skill 文件会自动生效有些不支持必须重启。具体看你用的工具建议查一下官方文档。 ## 6. 进阶玩法把 skills 用出花来 ### 6.1 用 skill 固化团队工作流 skills 最有价值的用法之一是把团队的工作流固化下来。比如你们团队的代码审查流程是先跑 lint再看测试覆盖率最后人工审查那就可以写一个代码审查的 skill把这三步写进去。AI 在审查代码的时候就会按照这个流程来不会漏掉任何一步。 我见过一个团队把他们的部署流程写成了 skill先跑测试再构建镜像再推送到仓库最后更新服务。AI 在收到部署指令时会自动按照这个流程执行每一步都有检查点出错就停下来报告。这比写一个部署脚本更灵活因为 AI 可以根据实际情况调整比如测试失败时自动分析原因。 ### 6.2 用 skill 做知识沉淀 skill 还可以用来沉淀团队知识。比如你们团队踩过一个坑数据库连接池不能设置太大否则会拖垮数据库。这个经验可以写成一个 skill触发条件是任务涉及数据库连接配置规则是连接池大小不超过 20超时时间设置为 30 秒。这样新来的同事在配置数据库时AI 就会提醒他注意这个问题避免重复踩坑。 这种经验型 skill的价值随着时间推移会越来越高。因为团队踩过的坑越多skill 里积累的经验就越丰富AI 的表现就越好。我建议每个团队都指定一个人负责维护 skills定期把新的经验补充进去。 ### 6.3 skill 的组合使用112 单个 skill 的能力有限但多个 skill 组合起来能产生意想不到的效果。比如你有一个生成代码的 skill 和一个生成测试的 skill当你让 AI实现一个功能并写测试时两个 skill 会协同工作先生成代码再根据代码生成测试。这种组合使用的方式能大幅提升开发效率。 组合使用的关键是**skill 之间的接口要清晰**。比如生成代码的 skill 输出的是代码文件生成测试的 skill 需要读取代码文件来生成测试。这两个 skill 之间就要约定好代码文件放在哪个目录、用什么命名规范。约定清楚了组合起来就很顺畅。 ### 6.4 用 skill 做多语言支持 如果你的项目涉及多种编程语言可以为每种语言写一个 skill。比如Python 规范TypeScript 规范Go 规范。AI 在处理不同语言的文件时会自动加载对应的 skill按照该语言的规范来输出。这样你就不需要在一个 skill 里写如果是 Python 就怎样如果是 TypeScript 就怎样逻辑更清晰维护也更方便。 我自己的项目里前端用 TypeScript后端用 Go脚本用 Python。我分别写了三个 skill每个 skill 只管一种语言。AI 在改前端代码时加载 TypeScript skill改后端代码时加载 Go skill互不干扰。这种分而治之的思路比写一个大而全的 skill 要好得多。 ## 7. 关于 skills 的一些个人体会 用了大半年 skills 之后我最大的感受是**skill 的质量取决于你对任务的理解深度**。如果你自己对某个任务的理解就是模糊的那写出来的 skill 也是模糊的AI 执行起来自然好不到哪去。反过来如果你能把一个任务拆解得很清楚知道每一步要做什么、注意什么那写出来的 skill 就会很精准AI 的表现也会很稳定。 另一个体会是**不要追求一次写出完美的 skill**。skill 是需要迭代的。我最早的几个 skill现在回头看简直惨不忍睹但正是通过不断使用、发现问题、修改才慢慢打磨出了好用的版本。所以我的建议是先写一个粗糙的版本用起来遇到问题就改改着改着就顺了。 最后说一个容易被忽略的点**skill 不是越多越好**。我见过有人装了上百个 skill结果 AI 每次启动都要加载半天而且经常触发错误的 skill。我的经验是常用的 skill 保持在 10 个以内每个都经过验证比装一堆用不上的要强得多。定期清理 skills 目录把不再用的删掉保持精简AI 的表现反而更稳定。 如果你刚开始接触 skills我的建议是从一个最简单的开始找一个你每天都要重复交代的要求把它写成 skill用一周看看效果。有效果就继续加没效果就调整。这种小步快跑的方式比一上来就搞一套复杂的 skill 体系要靠谱得多。