1. 从skills这个热词说起它到底在解决什么问题最近一段时间不管是在技术社区还是开发者群聊里skills这个词出现的频率高得离谱。很多人第一次看到它会以为是某种新的编程语言特性或者某个框架的插件系统。但如果你真的去翻一翻围绕 Claude Code、Codex、各类 agents 的讨论就会发现大家嘴里的 skills 其实指向一个很具体的东西给 AI 编程助手预置的一套可复用的能力包。我最早接触这个概念是因为团队里有人在用 Claude Code 做日常开发结果发现每次让它处理特定任务时都要重复写一大段提示词比如帮我按这个规范生成组件帮我检查这段代码的安全问题。写多了就烦而且不同人写的提示词质量参差不齐输出结果自然也不稳定。后来有人提出能不能把这些反复用到的指令、流程、约束条件打包成一个固定的东西让 AI 每次都能按同一套标准来干活这就是 skills 诞生的最朴素动机。说白了skills 就是把你怎么跟 AI 说话这件事标准化、模块化。它不是一个抽象概念而是一组实实在在的文件和配置里面写清楚了某个任务该怎么做、按什么顺序做、注意哪些坑、输出成什么格式。你可以把它理解成给 AI 助手准备的作业指导书——以前你得口头交代一遍现在直接把指导书递过去它照着执行就行。这个思路一旦成立价值就非常明显了。对于个人开发者来说skills 能帮你把重复劳动压缩掉对于团队来说skills 能保证所有人用 AI 产出的东西风格一致、质量可控对于更复杂的 agents 场景来说skills 就是让多个 AI 协作时不跑偏的共同语言。所以你会看到围绕 skills 的讨论迅速从这是什么变成了有哪些好用的 skills怎么自己写 skillsskills 和 plugin 有什么区别。这篇文章不打算给你堆一堆概念而是想把这几个月我在实际使用和折腾 skills 过程中积累的东西讲清楚。包括它背后的运行逻辑、怎么从零写一个能用的 skill、常见的坑在哪里、以及当 skills 和 Claude Code、Codex 这些工具结合时要注意什么。如果你正在用或者准备用 AI 编程助手这篇内容应该能帮你少走不少弯路。2. skills 的运行机制它凭什么能让 AI 记住你的要求2.1 从提示词工程到能力封装中间差了什么很多人会把 skills 和写一段好的提示词混为一谈觉得不就是把提示词存成文件吗这个理解只对了一半。提示词工程解决的是这一次怎么问而 skills 解决的是这一类任务以后都怎么问。前者是一次性的后者是可复用的。我举个实际例子。假设你要让 AI 帮你写一个 React 组件。普通的做法是每次打开对话框输入帮我写一个 React 组件用函数式写法带 TypeScript 类型样式用 CSS Modules不要用 any。这段话你写十次就是十次写一百次就是一百次。而 skill 的做法是把这段话连同更细的规范——比如命名用 PascalCase、props 必须定义 interface、事件处理函数用 handle 开头——全部写进一个结构化的文件里。以后你只需要说用组件 skill 写一个用户卡片AI 就会自动加载那套规范。这里的关键差异在于上下文的组织方式。普通提示词是散落在对话里的AI 每次都要重新理解而 skill 是有固定结构的它通常包含几个部分触发条件什么时候用这个 skill、执行步骤先做什么后做什么、约束规则不能做什么、输出格式结果长什么样。这种结构让 AI 在加载 skill 时能快速抓住重点而不是在一大段自然语言里猜你的意图。2.2 skill 文件里到底装了什么虽然不同工具对 skill 的具体格式要求不一样但核心组成是相通的。我拿自己写的一个代码审查 skill 来拆解你可以对照着看。第一部分是元信息。包括这个 skill 叫什么、什么场景下触发、适用哪些文件类型。这部分的作用是让 AI 知道我现在该不该用这个 skill。比如你写了一个专门审查 Python 的 skill那遇到 JavaScript 文件时就不应该触发它。第二部分是执行流程。这是 skill 的骨架通常用有序列表或者分步骤的方式写。比如代码审查 skill 的流程可能是先检查语法错误再看类型标注是否完整然后检查边界条件处理最后看有没有安全隐患。每一步还可以附带具体的检查点。第三部分是约束和禁忌。这部分特别重要因为 AI 很容易过度发挥。比如你要求它审查代码它可能顺手把代码重构了。所以在 skill 里要明确写只报告问题不修改代码如果发现问题按严重程度分级不确定的地方标注出来而不是瞎猜。第四部分是输出模板。规定结果用什么格式呈现。是表格、列表还是分段描述严重问题用什么标记这些都要写清楚否则每次输出格式都不一样后续处理起来很麻烦。提示skill 文件不是越长越好。我见过有人写了一个两千行的 skill结果 AI 加载后反而抓不住重点。一般来说单个 skill 控制在几百行以内把最关键的规则写清楚就够了。2.3 为什么 skills 能和 agents 配合得这么好单独看 skill它只是一个静态的说明书。但当它和 agents 结合时威力就出来了。Agent 的本质是能自主决策并执行多步任务的 AI而 skill 给它提供了做某类任务时的标准操作程序。打个比方agent 像一个新入职的员工能力很强但不知道你们公司的规矩。Skill 就是员工手册告诉他报销怎么走流程、代码提交有什么规范、跟客户沟通要注意什么。没有 skill 的 agent每次都要你手把手教有了 skill它就能按既定规则自主运转。在实际的 agents 场景里通常会有一个 skill 库agent 根据当前任务自动匹配并加载对应的 skill。比如一个负责前端开发的 agent遇到新建页面任务时加载页面脚手架 skill遇到性能优化任务时加载性能检查 skill。这种动态加载机制让一个 agent 能覆盖多种任务类型而不需要为每种任务单独训练一个模型。3. 动手写第一个 skill从需求拆解到落地验证3.1 先想清楚什么任务值得做成 skill不是所有事情都值得封装成 skill。我踩过的坑是一开始兴致勃勃地把各种零碎要求都写成 skill结果维护成本比收益还高。后来总结出一个判断标准这个任务是否高频、是否有固定套路、是否容易因为人为疏忽而出错。三个条件同时满足才值得做成 skill。高频很好理解一天要用好几次的才值得封装。有固定套路指的是任务步骤相对稳定不会每次都有大变化。容易出错则是指人工做的时候经常漏掉某些环节或者不同人做出来的结果差异很大。按这个标准我目前保留的 skill 主要有几类代码审查、组件生成、接口文档编写、提交信息规范化、以及特定框架的脚手架搭建。而那些一次性的、探索性的任务我从来不做成 skill因为做了也用不了几次。3.2 把老手直觉翻译成可执行步骤写 skill 最难的地方是把你自己做这件事时的直觉拆解成明确的步骤。因为老手做很多事情是下意识的你问他怎么做他说就那样做啊。但 AI 需要的是明确的指令。我的方法是边做边记录。比如我要写一个生成 API 接口的 skill我就先自己手动做一遍做的过程中把每个决策点记下来为什么先定义请求参数而不是响应结构为什么错误码要用这个格式为什么这个字段要加校验把这些为什么写进 skillAI 才能理解背后的逻辑而不是机械执行。还有一个技巧是找反例。想想你见过哪些做得不好的情况把这些反面案例写进 skill 的禁忌部分。比如不要生成没有错误处理的接口不要用模糊的类型定义不要在响应里暴露内部字段。反例往往比正例更能约束 AI 的行为。3.3 一个可复用的 skill 模板长什么样下面是我自己常用的一个 skill 结构模板你可以直接拿去改。注意不同工具的语法可能有差异但结构是通用的。# Skill 名称API 接口生成 ## 触发条件 - 用户要求生成新的 API 接口 - 涉及 RESTful 风格的 HTTP 接口 ## 前置检查 1. 确认接口的 HTTP 方法和路径 2. 确认请求参数和响应结构 3. 确认错误处理策略 ## 执行步骤 1. 定义请求参数类型包含必填/选填标注 2. 定义响应结构区分成功和失败两种情况 3. 编写接口处理逻辑包含参数校验 4. 添加错误处理覆盖参数错误、权限错误、服务错误 5. 生成接口文档注释 ## 约束规则 - 所有参数必须有类型定义 - 错误响应必须包含错误码和可读消息 - 不允许在响应中暴露数据库字段名 - 分页接口必须包含总数和页码信息 ## 输出格式 - 代码文件按项目现有结构放置 - 附带接口文档注释 - 如有新增依赖单独列出这个模板的好处是结构清晰AI 加载后能快速定位到关键信息。你可以根据具体任务调整章节但建议保留触发条件执行步骤约束规则这三个核心部分。3.4 写完怎么验证 skill 真的有效Skill 写完不是就完了必须验证。我的验证方法是用三个不同复杂度的任务去测试一个简单任务看基本流程是否跑通一个中等任务看约束规则是否生效一个边界任务看异常处理是否到位。比如测试 API 生成 skill 时我先让它生成一个最简单的 GET 接口看基本结构对不对。然后生成一个带分页和筛选的复杂接口看它有没有漏掉分页参数。最后故意给一个矛盾的输入比如生成一个不需要参数的 POST 接口看它会不会提出质疑而不是硬编。验证过程中发现的问题要回写到 skill 里。我一般会迭代三到五轮才能让一个 skill 稳定下来。第一版往往会有各种遗漏这很正常不要指望一次写完美。4. skills 和 Claude Code、Codex 结合时的实战细节4.1 Claude Code 里 skills 的加载逻辑Claude Code 对 skills 的支持核心思路是按需加载。它不会一次性把所有 skill 都塞进上下文而是根据当前任务判断该用哪个。这个机制的好处是节省上下文窗口坏处是如果 skill 的触发条件写得不够明确可能该加载的时候没加载。我在实际使用中发现Claude Code 判断是否加载某个 skill主要看 skill 描述里的关键词和当前任务的匹配度。所以写 skill 描述时要把可能触发的场景词都覆盖到。比如一个代码审查skill描述里最好同时包含review检查审查代码质量这些词提高匹配概率。另外要注意的是 skill 的优先级。如果你有多个 skill 可能匹配同一个任务Claude Code 会按某种顺序选择。我一般会把最常用的 skill 放在前面或者在描述里写清楚适用边界避免误触发。4.2 Codex 场景下 skills 的适配要点Codex 和 Claude Code 在 skill 处理上有些差异。Codex 更偏向于把 skill 当作一种配置来对待它期望 skill 的格式更结构化、更接近机器可读的规范。这意味着你在写 skill 时要减少自然语言的模糊表述多用明确的规则和条件。我踩过的一个坑是把为 Claude Code 写的 skill 直接搬到 Codex 上用结果因为描述太口语化Codex 理解偏差很大。后来我调整了写法把尽量用简洁的命名改成命名长度不超过 20 个字符使用小写字母和连字符效果就好多了。还有一个细节是 Codex 对 skill 的版本管理更敏感。如果你更新了 skill最好在文件里标注版本号和变更说明否则可能出现新旧行为不一致的情况。4.3 本地模型接入时的注意事项有些朋友会用本地模型来跑 skills这时候要注意模型的上下文长度和指令遵循能力。本地模型通常比云端模型小对长 skill 的处理能力有限。我的建议是如果要用本地模型把 skill 拆得更细一些每个 skill 只做一件事避免一个 skill 里塞太多步骤。另外本地模型对格式的敏感度更高。你在 skill 里写的输出模板最好用非常明确的标记比如用特定的分隔符或者固定的标题层级帮助模型理解结构。我试过用纯自然语言描述输出格式本地模型经常跑偏改成用代码块示例后就稳定多了。5. 那些没人告诉你但一定会踩的坑5.1 skill 冲突当两个 skill 同时想接管任务这是最常见的问题。你写了一个通用代码审查skill又写了一个Python 代码审查skill结果审查 Python 代码时两个 skill 都觉得自己该上场输出就乱了。解决办法是明确优先级和适用范围。通用 skill 的描述里写适用于所有语言但特定语言有专用 skill 时优先使用专用 skill。专用 skill 的描述里写清楚只适用于哪种语言。这样 AI 在匹配时就能做出正确选择。如果冲突还是频繁发生那就考虑合并。把通用 skill 和专用 skill 整合成一个用条件分支来处理不同语言的情况。虽然文件会大一些但至少不会打架。5.2 上下文污染skill 加载太多导致 AI 精神分裂有一次我同时加载了五六个 skill结果 AI 的输出风格变得很奇怪一会儿用这个规范一会儿用那个规范。后来才明白skill 之间如果有风格冲突同时加载就会互相干扰。我的经验是单次任务加载的 skill 不超过三个。如果确实需要多个 skill 配合那就把它们组织成一个复合 skill在里面明确执行顺序和各自负责的部分。比如前端页面开发这个复合 skill可以包含组件生成样式规范接口调用三个子部分按顺序执行。5.3 过度约束把 AI 管得太死反而不好用写 skill 的时候很容易陷入什么都想管的陷阱。我早期写的一个 skill光约束规则就列了三十多条结果 AI 执行时畏首畏尾稍微遇到规则没覆盖的情况就卡住了。后来我学会了抓大放小。只约束那些真正重要的、容易出错的地方其他细节留给 AI 自己判断。比如代码审查 skill我只强制要求必须报告安全问题和必须标注严重程度至于报告用什么措辞、按什么顺序排列就不管了。这样 AI 反而发挥得更好。5.4 版本失控改了 skill 之后行为不一致Skill 是会迭代的但迭代之后如果没有版本管理就会出现昨天还好好的今天怎么变了的情况。特别是团队协作时你改了 skill别人不知道用起来就会困惑。我的做法是在 skill 文件头部维护一个变更记录每次修改都记一笔改了什么、为什么改、影响范围是什么。如果是团队共用还要通知相关的人。另外重要 skill 的修改最好经过验证再合并不要直接改主版本。6. 从能用到好用skills 的进阶玩法6.1 让 skill 自己进化基于反馈的迭代机制Skill 不是写完就固定的好的 skill 会随着使用不断优化。我现在的做法是每次用 skill 处理任务后如果发现输出有问题就立刻记录下问题点攒够几个就统一更新 skill。更进一步的做法是让 AI 自己提改进建议。在 skill 里加一条规则执行完成后如果发现规则有模糊或不合理的地方请指出。这样 AI 在用的过程中会帮你发现 skill 的缺陷。我试过这个方法确实能发现一些自己想不到的问题。6.2 skill 组合用多个小 skill 拼出复杂能力单个 skill 的能力有限但组合起来就很强。我的思路是把复杂任务拆成多个原子 skill然后用一个调度 skill 来编排。比如新功能开发这个复杂任务可以拆成需求分析接口设计代码实现测试编写四个原子 skill调度 skill 负责按顺序调用它们并在中间传递上下文。这种做法的好处是每个原子 skill 都很简单容易维护和复用。缺点是调度逻辑需要额外设计而且上下文传递容易出问题。我一般只在任务确实复杂、且会反复出现时才这么做。6.3 团队协作怎么让大家的 skill 保持一致团队里每个人都可以写 skill但如果不统一管理很快就会乱套。我们的做法是建立一个共享的 skill 仓库所有人写的 skill 都提交到这里经过 review 后才能合并。Review 的重点是触发条件是否明确、约束规则是否合理、输出格式是否统一。另外我们还会定期清理不再使用的 skill。有些 skill 是特定项目用的项目结束后就没用了留在仓库里只会增加干扰。我一般每个季度过一遍把三个月内没被调用过的 skill 归档。7. 关于 skills 的几个常见误解7.1 skills 就是提示词模板这个误解最普遍。提示词模板是静态的文本替换而 skill 是动态的能力封装。Skill 可以根据上下文决定是否加载、加载哪部分、按什么顺序执行。它比提示词模板灵活得多也复杂得多。7.2 skill 写得越详细越好详细是好事但过度详细会适得其反。前面说过skill 太长会导致 AI 抓不住重点。而且太详细的 skill 维护成本很高改一个地方可能牵动全身。我的建议是先写核心规则遇到问题再补充不要一开始就追求面面俱到。7.3 有了 skills 就不需要人管了Skill 是辅助工具不是自动驾驶。它能把重复劳动标准化但不能替代人的判断。特别是遇到 skill 没覆盖的情况还是需要人来决策。我见过有人完全依赖 skill 输出结果出了错都不知道这是很危险的。8. 我个人的一些使用心得折腾 skills 这几个月最大的体会是skill 的质量取决于你对任务的理解深度。如果你自己都没想清楚这件事该怎么做写出来的 skill 一定是模糊的。所以写 skill 之前先花时间把任务拆解清楚比急着动手写更重要。另一个体会是不要追求一步到位。我第一个 skill 改了七八版才稳定下来中间推翻重来过好几次。这很正常skill 本身就是随着使用不断打磨的。刚开始写得粗糙没关系用起来发现问题再改就是了。还有就是保持 skill 的简洁。我现在写 skill 的原则是能用三行说清楚就不用五行能用一个规则解决就不写两个。简洁的 skill 更容易维护也更容易被 AI 正确执行。最后说一个实际的小技巧如果你不确定某个规则该不该写进 skill就先不写观察几次。如果发现 AI 确实经常在这个地方出错再补进去。这样能避免 skill 里塞太多不必要的约束。