1. 从skills这个热词说起它到底在解决什么问题最近一段时间不管是在开发者社区还是各类技术群聊里skills这个词出现的频率高得离谱。很多人第一次看到它会下意识以为是某种新的编程语言或者框架其实不是。这里的 skills指的是围绕 AI 编程助手比如 Claude Code、Codex 这类工具构建的一套可插拔能力扩展机制。你可以把它理解成给 AI 助手装的技能包——原本它只会聊天、写代码装上 skills 之后它能按照你预设的流程去查数据库、跑测试、生成规范文档、甚至调用外部工具完成一整套操作。我最初接触这个概念的时候也是懵的。因为skills这个词太泛了泛到你在搜索引擎里敲进去出来的结果从安卓脱壳 skills到前任 skills 官方下载什么都有。但真正有价值的那个方向是AI Agent 的能力扩展。Claude Code 和 Codex 这两个工具本质上都是把大模型包装成了一个能在你本地终端或编辑器里干活的编程搭子而 skills 就是教这个搭子遇到某类任务时该按什么套路出牌的说明书。为什么这件事值得单独拿出来讲因为大多数人用 AI 编程助手的方式还停留在我问它答的阶段——你贴一段报错它给你一段修复建议然后你自己去改。这种用法效率提升有限因为真正的瓶颈不在生成代码这一步而在理解上下文、执行多步操作、验证结果这一整条链路上。skills 的价值就在于把这条链路固化下来让 AI 从顾问变成执行者。举个我自己的例子。之前每次让 AI 帮我写单元测试都要反复交代项目用的测试框架、断言风格、mock 方式、目录结构。后来我把这些约定写成了一个 skill之后只要说一句给这个模块补测试它就能按照我项目里的规范直接产出可用的测试文件连 import 路径都不会写错。这就是 skills 最朴素也最实用的价值把重复的上下文交代变成一次性的能力沉淀。这篇文章适合谁看如果你已经在用 Claude Code 或 Codex但还停留在聊天式用法那这篇能帮你把效率再往上提一个台阶。如果你还没开始用这类工具也没关系我会把安装、配置、skill 编写这些环节都拆开讲清楚你跟着走一遍就能上手。全文会围绕 skills 的核心机制、实际编写方法、常见坑点、以及和 plugin、agents 这些概念的关系展开尽量做到看完就能动手。2. skills、plugin、agents 三个概念到底怎么区分很多人一上来就被这三个词绕晕了。它们确实容易混因为在实际使用中经常一起出现而且不同工具的命名习惯还不一样。我用自己的理解方式给你捋一遍不追求学术严谨追求的是你听完能分清。2.1 skills 是怎么做agents 是谁来做skills 本质上是一份操作指南。它描述的是当遇到某类任务时应该按照什么步骤、用什么工具、遵循什么规范去完成。它不主动发起任务也不决定什么时候被调用它只是静静地躺在那里等合适的时机被触发。agents 则更像是一个执行主体。你可以把 agent 理解成一个有自主决策能力的小助手它会根据当前任务判断该调用哪个 skill、该用什么工具、下一步该干什么。一个 agent 可以挂载多个 skills就像一个人可以掌握多项技能一样。打个比方skills 是菜谱agents 是厨师。菜谱告诉你红烧肉要先用冰糖炒糖色但菜谱自己不会做菜厨师会看菜谱也会根据手头食材决定今天做红烧肉还是回锅肉。你给厨师配的菜谱越多他能做的菜就越丰富。2.2 plugin 是装东西的盒子plugin 这个词在软件领域用得太久了它的含义相对固定一种把功能打包分发的形式。在 skills 的语境下plugin 通常指的是把一组相关的 skills、配置、依赖打包成一个可安装的单元。你安装一个 plugin可能一次性获得好几个 skills外加一些预设的 agent 配置。这里有个容易踩的坑不同工具对 plugin 的定义边界不一样。有的工具里 plugin 就是 skill 的集合有的工具里 plugin 还包含了 UI 扩展、命令注册等更重的东西。所以你在看文档的时候别默认所有平台的 plugin 都是一个意思一定要看具体工具的说明。2.3 三者的协作关系把这三个概念串起来看一个典型的运行流程是这样的你安装了一个 plugin里面包含了若干个 skills 和一个预设的 agent 配置。你在对话里提出一个任务比如帮我重构这个函数。agent 接收到任务判断这属于代码重构类操作。agent 查找挂载的 skills找到对应的重构 skill。agent 按照 skill 里定义的步骤执行先读代码、再分析依赖、然后生成新版本、最后跑测试验证。这个流程里skill 决定了质量下限——只要 skill 写得够细AI 的输出就不会太离谱agent 决定了灵活上限——好的 agent 能在 skill 覆盖不到的场景里做出合理判断。概念本质是否主动执行典型载体skills操作指南/流程定义否被动触发Markdown 文件、配置文件agents执行主体/决策者是主动调度配置项、模型工具组合plugin分发打包单元否安装包、目录结构理解了这三者的关系后面讲 skill 编写的时候你就不会迷糊——我们写的每一份 skill最终都是给某个 agent 用的而它可能通过某个 plugin 被分发出去。3. 一个 skill 文件里到底该写什么这是最核心的部分。很多人第一次写 skill写出来的东西要么太笼统帮我写好代码要么太琐碎把每一行代码都规定死。这两种都不对。一个好的 skill应该像一份给聪明新人的交接文档——他知道怎么编程但不了解你这个项目的特殊约定你要把那些只有老员工才知道的东西告诉他。3.1 skill 的基本结构不同工具的 skill 格式略有差异但核心要素是相通的。一个完整的 skill 通常包含这几块名称与描述让 agent 知道这个 skill 是干什么的什么时候该用它。触发条件什么情况下应该激活这个 skill。写得太宽会导致误触发写得太窄会导致该用的时候用不上。执行步骤具体的操作流程这是 skill 的主体。约束与禁忌哪些事绝对不能做哪些边界不能越。示例给一两个输入输出的例子帮助 agent 理解预期效果。我见过太多 skill 只写了执行步骤结果 agent 在不该用的时候用了或者用了之后产出不符合预期。触发条件和约束这两块往往比步骤本身更重要因为它们决定了 skill 的适用边界。3.2 描述怎么写才不会被误触发触发条件这块我的经验是用任务特征而不是关键词来描述。比如你写一个生成 API 文档的 skill如果你写当用户提到文档时触发那用户说这个文档写得不好也会触发这就错了。更好的写法是描述任务特征当用户要求为某个模块或接口生成结构化说明文档且需要包含参数、返回值、示例时触发。再比如如果你有多个 skill 都涉及代码修改那触发条件就要写得更精确避免 agent 在多个 skill 之间反复横跳。我一般的做法是给每个 skill 加一个不适用场景的说明明确告诉 agent 什么情况下不要用这个 skill。这招很管用能挡掉大部分误触发。3.3 执行步骤的颗粒度怎么把握这是最考验经验的地方。步骤写太粗agent 会自由发挥产出不稳定写太细agent 会变成机械执行遇到稍微不同的情况就卡住。我的建议是按决策点来划分步骤而不是按操作来划分。什么意思就是每一步应该对应一个需要判断的节点而不是一个机械动作。举个例子写一个修复 bug的 skill不好的写法按操作划分读取报错信息打开相关文件修改代码运行测试好的写法按决策点划分解析报错信息判断错误类型语法错误/逻辑错误/环境问题根据错误类型定位相关代码范围分析根因确认是代码问题还是配置问题如果是代码问题生成修复方案并说明理由如果是配置问题给出配置调整建议修复后运行相关测试确认问题解决且未引入新问题看出区别了吗好的写法里每一步都包含判断和分支agent 在执行时有了思考空间而不是盲目照做。3.4 约束与禁忌那些绝对不能做的事这部分经常被忽略但它是保证 skill 安全性的关键。比如不要在没有备份的情况下删除文件不要修改项目配置文件中的敏感字段不要在未确认的情况下执行数据库写操作不要引入项目里没有的新依赖这些约束看起来是常识但 AI 在执行任务时很容易为了达成目标而走捷径。明确写出来能挡掉很多麻烦。我自己就遇到过一次让 AI 帮我清理无用代码结果它把一段看起来没用但实际上被反射调用的代码删了导致运行时才报错。后来我在 skill 里加了一条删除任何代码前先搜索整个项目确认没有动态引用这类问题就再没出现过。4. 从零写一个能用的 skill完整实操光讲理论没意思我们直接动手写一个。假设你有一个前端项目用的是 React TypeScript团队约定了一些代码规范。你想写一个 skill让 AI 在帮你写组件时自动遵循这些规范。4.1 先明确这个 skill 的边界在动手之前先问自己几个问题这个 skill 解决什么问题——让 AI 生成的 React 组件符合团队规范。什么时候触发——当用户要求新建组件或修改组件结构时。什么时候不触发——当用户只是问概念、或者修改的是非组件文件时。产出物是什么——符合规范的 .tsx 文件包含类型定义、样式、测试。把这几个问题想清楚skill 的骨架就有了。4.2 写触发条件触发条件我一般写成这样当用户要求创建新的 React 组件、或将现有代码重构为组件时激活。不适用于纯逻辑函数、工具类、配置文件、样式文件的修改。这样写的好处是agent 能清楚知道边界在哪。如果用户说帮我写个格式化日期的函数它就不会傻乎乎地去套组件模板。4.3 写执行步骤步骤部分我按决策点来组织确认组件类型判断是展示型组件纯 UI还是容器型组件含数据逻辑。展示型组件不引入状态管理容器型组件需要明确数据来源。确定文件位置根据项目目录约定展示型组件放在components/下容器型组件放在containers/下。如果项目结构不同先读取现有目录结构再决定。生成组件骨架包含 import 语句、类型定义Props 接口、组件函数、导出语句。类型定义必须显式声明不允许用any。处理样式优先使用项目已有的样式方案CSS Modules / styled-components / Tailwind不引入新的样式库。补充测试如果项目有测试目录生成对应的测试文件覆盖渲染和主要交互。自检检查是否所有 Props 都有类型、是否有未使用的 import、是否符合命名规范。每一步都包含判断agent 执行时不会僵化。4.4 写约束约束部分我列了这么几条不引入项目 package.json 中未声明的依赖不使用any类型必要时用unknown加类型守卫组件文件名使用 PascalCase与组件名一致不修改项目根目录下的配置文件生成测试时不 mock 掉被测组件本身这些约束都是踩过坑之后总结出来的。比如不使用 any这条是因为之前 AI 为了省事经常用 any 绕过类型检查导致类型系统形同虚设。4.5 加一个示例示例部分我放了一个输入输出对照输入帮我写一个用户头像组件接收 url 和 size 两个属性输出一个完整的 Avatar.tsx 文件包含 Props 类型定义、默认 size 值、图片加载失败时的占位处理、以及对应的测试文件。有了这个示例agent 对符合规范的理解会准确很多。5. 安装与配置环节最容易卡住的地方skill 写好了怎么让它生效这一步看起来简单实际上坑不少。我按常见工具分别说一下。5.1 Claude Code 的 skill 加载机制Claude Code 加载 skill 的方式通常是把 skill 文件放在指定的目录下然后在配置里声明。这里最容易出问题的是路径问题。很多人把 skill 文件放错目录或者配置里写的路径和实际路径不一致导致 skill 根本不生效但工具又不会报错你就一直纳闷为什么 AI 不按套路出牌。我的建议是配置完之后先用一个明确的测试任务验证 skill 是否被加载。比如你的 skill 是管组件生成的那就直接让它生成一个组件看产出是否符合规范。如果不符合先检查路径再检查触发条件是不是写得太窄。另一个常见问题是编码格式。skill 文件如果是中文内容一定要确保是 UTF-8 编码否则可能出现乱码导致解析失败。这个问题在 Windows 环境下尤其常见。5.2 Codex 的 skill 配置Codex 这边的配置逻辑类似但它在 skill 的组织方式上可能更偏向于项目级配置——也就是 skill 跟着项目走而不是全局生效。这样做的好处是不同项目可以用不同的 skill 集不会互相干扰坏处是你换一个项目就得重新配一遍。我的做法是维护一个基础 skill 库放在一个公共目录里然后在各个项目的配置里引用。这样既保证了复用又保留了项目级的定制空间。5.3 本地模型接入时的注意事项有些人会用本地模型来跑这些工具这时候 skill 的生效情况可能会受影响。因为不同模型对指令的遵循程度不一样有些小模型对复杂的 skill 描述理解不到位执行时会打折扣。如果你用的是本地模型建议把 skill 写得更直白一些减少抽象描述多用具体例子。另外skill 的长度也要控制太长的 skill 在小模型上容易被截断或忽略后半部分。我一般会把核心约束放在 skill 的开头确保即使后面被截断关键信息也已经传达。5.4 验证 skill 是否生效的土办法除了直接跑任务看结果我还有一个土办法在 skill 里加一条激活时输出一行提示的指令。比如让 agent 在应用这个 skill 时先说一句正在使用 XX 规范生成组件。这样你一眼就能看出 skill 有没有被触发。等确认没问题了再把这行提示去掉。这个方法虽然笨但特别有效尤其是在调试触发条件的时候。6. 那些让我踩过坑的细节写 skill 这件事看别人写觉得挺简单自己上手才知道坑有多密。我挑几个印象最深的说说。6.1 触发条件写太宽导致 skill 到处乱入我最早写的一个 skill 是管代码格式的触发条件写的是当涉及代码修改时。结果不管我让它干什么它都要先给我讲一遍格式规范烦得不行。后来改成当用户明确要求格式化代码、或生成的代码需要符合项目风格时才消停。这个坑的本质是AI 对涉及这个词的理解比人宽泛得多。你觉得涉及代码修改是指主要任务是改代码它理解成只要提到代码就算。所以触发条件要用具体的任务描述别用模糊的动词。6.2 skill 之间互相冲突当你装了多个 skill它们之间可能会打架。比如一个 skill 说生成代码时要加详细注释另一个 skill 说保持代码简洁避免冗余注释。AI 遇到这种情况会随机选一个或者干脆两个都不听。解决办法是给 skill 分优先级或者在触发条件里明确互斥关系。我一般的做法是把通用性强的 skill 设为低优先级把场景特定的 skill 设为高优先级这样特定场景下会覆盖通用规则。6.3 skill 更新后不生效这个坑很隐蔽。你改了 skill 文件但工具可能缓存了旧版本导致新内容不生效。不同工具的缓存机制不一样有的需要重启有的需要手动清缓存。我的习惯是每次改完 skill先重启一次工具再做验证。虽然麻烦但能避免改了跟没改一样的困惑。另外如果你用的是版本控制记得确认改的是当前生效的那个分支的文件别改了半天改的是另一个副本。6.4 过度依赖 skill 导致灵活性下降这是理念层面的坑。skill 用多了你会不自觉地想把所有事情都流程化结果遇到 skill 覆盖不到的场景时AI 反而不知道怎么处理了。我的经验是skill 应该覆盖高频、标准化程度高的任务低频、需要灵活判断的任务还是交给 agent 自由发挥。比如生成 CRUD 接口这种高度模式化的任务适合写 skill设计系统架构这种需要权衡的任务就不适合。7. skill 写得好不好看这几个信号最后说说怎么判断一个 skill 的质量。我总结了几个信号你可以拿来对照自己的 skill。信号一AI 的输出是否稳定。同一个任务跑三次如果产出结构、风格、质量都差不多说明 skill 约束到位了如果每次都不一样说明 skill 写得太松。信号二是否减少了你的重复交代。好的 skill 应该让你不用再反复说记得加类型记得写测试这类话。如果你发现还是得每次提醒说明 skill 没覆盖到这些点。信号三是否减少了返工。如果 AI 按 skill 产出的东西你基本不用改或者只改少量细节说明 skill 的规范定义得准如果每次都要大改说明 skill 里的规范和你实际想要的不一致。信号四是否容易维护。skill 不是写完就完了项目规范变了、工具升级了skill 都得跟着改。如果一个 skill 写得特别复杂、牵一发动全身那维护成本就太高了。我倾向于把 skill 拆小每个 skill 只管一件事这样改起来影响面小。信号五新人能不能看懂。这个信号有点反直觉但很管用。如果你的 skill 拿给一个不熟悉项目的人看他能大致明白哦原来这个项目是这么干的那说明 skill 写得清晰如果他自己都看不懂那 AI 大概率也理解不到位。说到底skill 的本质是把你的隐性知识显性化。你脑子里那些我们项目就是这么干的的约定通过 skill 变成了 AI 能读懂的文档。这个过程本身就有价值因为它逼着你把模糊的经验整理成清晰的规则。哪怕你最后不用 AI这份整理出来的规范对团队也是有用的。我现在维护着十几个 skill覆盖了组件生成、接口对接、测试编写、文档产出等场景。它们不是一次写完的而是每次遇到AI 又没按我想的来的时候就补一条规则进去。慢慢地AI 越来越像团队里的老成员而不是一个需要反复调教的新人。这个过程没什么捷径就是不断用、不断改、不断沉淀。