1. 从“skills”这个热词说起：它到底在解决什么问题
最近半年，不管是在技术群还是各种开发者社区，“skills”这个词出现的频率高得离谱。你随便翻一下热搜词列表就能看到：skills、claude code、codex、plugin、agents、find skills、skills推荐、codex skills、claude agent skills……这些词几乎都指向同一个东西——给 AI 编程助手装上一套可复用的“技能包”。
我先用大白话解释一下这个概念。你可以把 Claude Code、Codex 这类 AI 编程工具想象成一个刚入职的实习生，脑子很聪明，但对你公司的代码规范、项目结构、常用命令一无所知。每次你让它干活，都得从头交代一遍：“我们用的是 pnpm 不是 npm”“提交信息要遵循 Conventional Commits”“测试跑 vitest 不是 jest”。说一次两次还行，天天说谁都受不了。
skills 就是把这些重复交代的东西固化下来，变成 AI 可以自动加载的“技能说明书”。一个 skill 本质上就是一个结构化的文件夹，里面包含一段描述（告诉 AI 这个技能是干什么的、什么时候该用）加上具体的指令、脚本或者参考资料。AI 在接到任务时，会先扫描有哪些可用的 skills，然后按需加载对应的那个，就像人翻手册一样。
这件事为什么重要？因为它把 AI 编程从“每次都要手把手教”推进到了“一次配置、长期复用”的阶段。对于每天都要和 AI 结对编程的人来说，skills 直接决定了你是在高效产出还是在反复解释。适合读这篇内容的人很明确：已经在用或者准备用 Claude Code、Codex 这类工具的开发者，尤其是那些觉得“AI 挺好用但总差一口气”的人。
我下面会从设计思路、核心机制、实操落地、踩坑排查几个角度，把 skills 这套东西彻底拆开讲清楚。内容会涉及 Claude Code 和 Codex 两个主流平台，也会提到 plugin、agents 这些相关概念怎么和 skills 配合。
2. skills 的整体设计与核心思路拆解
2.1 为什么是“技能包”而不是“配置文件”
很多人第一次接触 skills 会有一个疑问：我直接写一个.cursorrules或者CLAUDE.md不就行了吗，为什么要搞这么复杂的文件夹结构？
这个问题的答案藏在上下文窗口的经济学里。你写的每一段指令都会占用 AI 的上下文 token，而上下文是有限且昂贵的。如果你把所有规范、所有命令、所有项目背景都塞进一个全局配置文件，那每次对话一开始就消耗掉大量 token，而且大部分内容跟当前任务根本无关。
skills 的设计精髓在于渐进式披露（progressive disclosure）。AI 启动时只加载每个 skill 的“元数据”——也就是名字和一句简短描述，这部分非常轻量。只有当 AI 判断当前任务需要用到某个 skill 时，才会把它的完整内容读进来。这就像你书架上摆了一排工具书，你不需要把每本书都背下来，只需要知道哪本书讲什么，用到的时候再翻。
提示：这个设计思路直接决定了你写 skill 描述的方式。描述写得好不好，直接决定 AI 能不能在正确的时机找到正确的技能。描述写得太笼统，AI 要么该用的时候想不起来，要么不该用的时候乱加载。
2.2 Claude Code 和 Codex 在 skills 上的路线差异
虽然都叫 skills，但 Claude Code 和 Codex 的实现路线有明显区别，理解这个差异对你选型很关键。
Claude Code 的 skills 体系更偏向文件系统驱动。它有一套约定俗成的目录结构，skill 放在特定路径下，通过SKILL.md文件来定义。Claude Code 还支持从官方市场或者团队仓库拉取 skills，社区生态相对活跃。你在热搜里看到的claude 国内安装skills 官方市场、claude code 安装这些词，反映的就是大家在找怎么把 skills 装进 Claude Code。
Codex 这边的 skills 更强调和 agent 工作流的绑定。Codex 本身就是一个 agent 化的编程助手，skills 在它这里更像是给 agent 扩展能力的插件。热搜里的codex skills、codex接入deepseek、codex好用的skills说明大家关心的是怎么让 Codex 通过 skills 接入不同的模型或者工具链。
我的建议是：如果你主要用 Claude Code，重点研究它的目录约定和官方市场；如果你用 Codex，重点研究它怎么把 skill 和 agent 任务编排结合起来。两者不是互斥的，很多人两个都在用。
2.3 plugin、agents、skills 三者的关系
这三个词经常一起出现，但很多人搞不清它们的边界。我用一个类比来说明：
- skills是“技能”，比如“会写单元测试”“会做代码审查”“会生成数据库迁移脚本”。
- agents是“执行者”，是一个能自主规划、调用工具、完成多步任务的智能体。一个 agent 可以拥有多个 skills。
- plugin是“插件”，是更外层的打包和分发机制。一个 plugin 里可以包含若干个 skills，甚至包含 agent 的配置。
所以它们的关系是层层包含的：plugin 打包 skills，agent 使用 skills。热搜里的dsh plugin --profile web add dshmarket、idea设置plugin中插件仓库地址这些，说的就是 plugin 层面的安装和配置。理解了这层关系，你在看各种文档时就不会晕。
3. 核心细节解析与实操要点
3.1 一个 skill 的最小结构长什么样
不管哪个平台，一个 skill 的核心结构都差不多。我以最常见的SKILL.md形式来说明，这是 Claude Code 体系里最标准的做法。
一个 skill 文件夹通常包含：
my-skill/ ├── SKILL.md # 必需，技能的主定义文件 ├── scripts/ # 可选，放可执行脚本 ├── references/ # 可选，放参考资料 └── assets/ # 可选，放模板、图片等SKILL.md本身由两部分组成：YAML frontmatter和Markdown 正文。frontmatter 里最关键的是name和description两个字段。
--- name: api-test-generator description: 当用户需要为 REST API 生成集成测试时使用。适用于 Express、Fastify、NestJS 项目，输出 vitest 或 jest 格式的测试文件。 --- # API 测试生成器 ## 使用场景 当用户提到"给这个接口写测试""生成 API 测试""补充集成测试"时触发。 ## 执行步骤 1. 读取目标路由文件，识别 HTTP 方法和路径 2. 检查项目使用的测试框架（看 package.json） 3. 按照项目现有的测试风格生成测试用例 4. 覆盖正常路径、边界条件、错误处理三类场景 ## 注意事项 - 不要生成 mock 数据库的测试，本项目用真实测试库 - 测试文件命名遵循 `*.test.ts` 规范这个结构看起来简单，但每个部分都有讲究。description字段是 AI 决定是否加载这个 skill 的唯一依据，所以它必须同时说清楚“做什么”和“什么时候用”。我见过太多人把 description 写成“一个测试生成工具”，结果 AI 永远想不起来用它。
3.2 description 的写法决定了 skill 的命中率
这是我要重点强调的一点，也是很多人踩坑的地方。description 不是给你看的，是给 AI 做语义匹配用的。它需要包含三类信息：
第一类是能力描述，说明这个 skill 能做什么。第二类是触发条件，说明什么情况下应该用。第三类是适用范围，说明它适合什么技术栈或场景。
我对比两种写法你就明白了：
| 写法 | description 内容 | 实际效果 |
|---|---|---|
| 差 | 生成测试 | AI 不知道什么时候该用，经常漏掉 |
| 好 | 当用户需要为 REST API 生成集成测试时使用。适用于 Express、Fastify、NestJS 项目，输出 vitest 或 jest 格式的测试文件 | AI 能在用户提到 API 测试时准确命中 |
实测下来，description 里包含具体的技术栈名称和用户可能说的自然语言短语，命中率能提升一大截。你可以把用户可能说的原话都塞进去，比如“写测试”“补测试”“生成测试用例”这些。
3.3 脚本和参考资料怎么放
skill 不只是文字指令，它还可以带可执行脚本。这是它比普通配置文件强大的地方。
举个例子，你有一个 skill 是“生成数据库迁移文件”。你可以放一个scripts/gen-migration.sh脚本，然后在SKILL.md里写：“执行scripts/gen-migration.sh <table_name>来生成迁移文件”。AI 在需要的时候会直接调用这个脚本，而不是自己瞎编一个迁移文件。
参考资料（references）则适合放那些“AI 需要知道但不需要每次都读”的内容。比如你项目的 API 规范文档、数据库 schema 说明、第三方服务的接口文档。AI 在需要的时候会去读这些文件，平时不占用上下文。
注意：脚本一定要做好参数校验和错误处理。AI 调用脚本时可能传错参数，如果脚本直接崩了，AI 会陷入困惑。我一般会在脚本开头加一段参数检查，参数不对就输出清晰的错误信息，这样 AI 能自己纠正。
3.4 安装路径和加载机制
不同平台的 skill 存放路径不一样，这是新手最容易卡住的地方。
Claude Code 通常会在项目根目录或者用户主目录下寻找 skills。项目级的 skills 放在.claude/skills/下，用户级的放在~/.claude/skills/下。项目级的优先级更高，适合放跟当前项目强相关的技能；用户级的适合放你个人通用的技能。
Codex 的路径约定略有不同，具体要看版本。热搜里codex安装、codex安装教程、codex安装包这些词热度很高，说明很多人在初次配置阶段。我的建议是先把官方文档的路径约定确认清楚，别凭感觉放，放错地方 AI 根本扫不到。
加载机制上，AI 启动时会扫描所有 skill 目录，读取每个SKILL.md的 frontmatter。这个过程很快，因为只读元数据。当对话进行到某个节点，AI 判断需要某个 skill 时，才会读取完整内容。所以你不用担心装了几十个 skill 会拖慢启动。
4. 实操过程与核心环节实现
4.1 从零搭建第一个 skill 的完整流程
我拿一个真实场景来演示：给一个用 pnpm + vitest 的 TypeScript 项目，做一个“代码审查”skill。
第一步，确定目录。在项目根目录创建.claude/skills/code-review/SKILL.md。
第二步，写 frontmatter。这一步最关键，我反复打磨过很多次：
--- name: code-review description: 当用户要求审查代码、检查代码质量、review PR 或者提到"看看这段代码有没有问题"时使用。适用于 TypeScript/JavaScript 项目，重点关注类型安全、错误处理、性能隐患和测试覆盖。 ---第三步，写正文。正文要分清楚“什么时候用”“怎么做”“注意什么”：
# 代码审查技能 ## 审查维度 1. 类型安全：有没有 any、类型断言是否滥用 2. 错误处理：异步操作有没有 catch、边界条件有没有处理 3. 性能：有没有不必要的循环、有没有 N+1 查询 4. 测试：新增逻辑有没有对应测试 ## 执行步骤 1. 先用 git diff 看本次改动范围 2. 逐个文件审查，按上面的维度打分 3. 输出审查报告，按严重程度排序 4. 对每个问题给出具体的修改建议 ## 输出格式 用表格列出问题，包含：文件路径、行号、问题描述、严重程度、修改建议第四步，测试。故意写一段有问题的代码，让 AI 审查，看它能不能触发这个 skill。如果没触发，回去改 description。
第五步，迭代。用了几次之后你会发现有些问题 AI 总是漏掉，把这些补充到审查维度里。skill 是活的，要持续打磨。
4.2 参数计算：skill 数量多少合适
很多人一上来就想装几十个 skill，觉得越多越强大。这是个误区。
每个 skill 的元数据都会占用一点上下文，虽然不多，但几十个加起来也可观。更重要的是，skill 太多会导致 AI 的选择困难——两个 skill 的 description 有重叠时，AI 可能选错。
我的经验值是：项目级 skill 控制在 5 到 10 个，用户级 skill 控制在 10 到 15 个。超过这个数量，就要考虑合并或者删减。
怎么判断该不该合并？如果两个 skill 经常在同一个任务里一起被用到，那它们大概率应该合并成一个。比如“写测试”和“跑测试”经常一起出现，可以合并成“测试工作流”。
4.3 用 plugin 机制批量分发 skills
当你有一套成熟的 skills，想分享给团队或者社区时，plugin 机制就派上用场了。
一个 plugin 本质上是一个包含多个 skills 的仓库，加上一个清单文件。清单文件里声明这个 plugin 包含哪些 skills、版本号、依赖关系等。团队成员通过一条命令就能把整套 skills 装到本地。
热搜里的dsh plugin --profile web add dshmarket就是这类操作的典型命令。不同平台的命令格式不一样，但思路是一致的：指定一个源，把 plugin 拉下来，解压到对应的 skills 目录。
提示：做团队级 plugin 时，一定要做版本管理。skills 的更新会直接影响团队所有人的 AI 行为，没有版本管理的话，某天你改了一个 skill，别人那边行为突然变了，排查起来很痛苦。我一般用语义化版本，破坏性变更升大版本。
4.4 让 skill 和 agent 工作流配合起来
单独的 skill 是静态的，只有和 agent 的动态执行结合起来，才能发挥最大价值。
举个例子，你可以配置一个“PR 审查 agent”，它的工作流是：拉取 PR 的 diff，调用 code-review skill 做审查，调用 test-runner skill 跑测试，最后把结果汇总成评论发到 PR 上。整个流程里，agent 负责编排，skills 负责具体能力。
Codex 在这方面做得比较自然，因为它本身就是 agent 优先的设计。Claude Code 则需要你通过配置或者提示词来引导 agent 行为。热搜里的langchain deep agents、agents anywhere反映的就是大家在探索 agent 编排的各种方案。
5. 常见问题与排查技巧实录
5.1 skill 不触发怎么办
这是最高频的问题。你辛辛苦苦写了一个 skill，结果 AI 该用的时候不用，急死人。
排查顺序是这样的：
第一，检查路径。确认 skill 放在正确的目录下，文件名是SKILL.md而不是skill.md或者SKILLS.md。大小写敏感的系统上，这个错误很常见。
第二，检查 frontmatter 格式。YAML 对缩进极其敏感，多一个空格少一个空格都可能解析失败。我建议用在线 YAML 校验工具过一遍。
第三，检查 description。这是最常见的原因。把 description 读一遍，问自己：如果我是 AI，看到用户说“帮我看看这段代码”，我会想到加载这个 skill 吗？如果答案是否定的，就改 description。
第四，检查是否有冲突。如果两个 skill 的 description 高度相似，AI 可能选了另一个。把它们的触发条件区分得更明确一些。
5.2 skill 加载了但行为不对
有时候 skill 确实触发了，但 AI 的执行结果不符合预期。这通常是正文写得不够明确。
AI 不是人，它不会“领会精神”。你写“注意代码质量”，它不知道具体指什么。你写“检查有没有 any 类型、有没有未处理的 Promise rejection、有没有硬编码的密钥”，它就能准确执行。
我的经验是：正文里的每一条指令都要具体到可以机械执行的程度。模糊的形容词是 skill 的天敌。
5.3 常见问题速查表
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
| skill 完全不触发 | 路径错误或文件名不对 | 确认目录结构和文件名大小写 |
| skill 偶尔触发 | description 不够具体 | 补充技术栈和用户常用短语 |
| skill 触发但结果差 | 正文指令太模糊 | 把每条指令具体化、可执行化 |
| 多个 skill 冲突 | description 重叠 | 明确区分触发条件，或合并 |
| 脚本调用失败 | 参数校验缺失 | 脚本开头加参数检查和清晰报错 |
| 更新 skill 后行为没变 | 缓存未刷新 | 重启 AI 工具或清理缓存 |
| 团队协作时行为不一致 | 版本不同步 | 用 plugin + 版本管理统一分发 |
5.4 几个我踩过的坑
第一个坑是在 description 里写太多技术细节。我一开始觉得写得越详细越好，结果 description 太长，AI 匹配时反而抓不住重点。后来我改成：description 只写“做什么”和“什么时候用”，技术细节全部放到正文里。
第二个坑是skill 之间互相依赖但没声明。我有一个 skill 依赖另一个 skill 生成的输出格式，但没在文档里说明。结果单独用第二个 skill 时，AI 不知道输入格式，输出乱七八糟。后来我在每个有依赖的 skill 里都明确写了“前置条件”和“输入格式要求”。
第三个坑是忽略了不同 AI 工具的差异。同一个 skill 在 Claude Code 里工作正常，换到 Codex 就行为不对。原因是两个平台对 skill 的解析细节有差异，比如对 frontmatter 字段的支持程度不同。所以跨平台使用时，要针对每个平台做适配测试。
第四个坑是skill 写得太“聪明”。我试图让一个 skill 处理所有类型的测试生成，结果它什么都做不好。后来拆成三个：单元测试、集成测试、端到端测试，每个都专注一个场景，效果立刻上来了。skill 要专一，不要贪多。
5.5 关于安全和权限的提醒
skill 里的脚本是有执行权限的，这一点必须重视。你从社区下载的 skill，里面的脚本可能做任何事。我建议：
- 安装第三方 skill 前，把里面的脚本通读一遍
- 不要在 skill 脚本里硬编码密钥或敏感信息
- 团队共享的 skill 要走代码审查流程
- 定期清理不再使用的 skill，减少攻击面
热搜里agentpoison: red-teaming llm agents via poisoning memory or knowledge ba这个词反映的就是 agent 和 skill 被投毒的风险。虽然这是研究性质的话题，但提醒我们：skill 作为一种能被 AI 自动加载和执行的东西，它的安全性值得认真对待。
6. 进阶玩法：让 skills 真正融入你的开发流
6.1 按项目阶段组织 skills
我现在的做法是按开发阶段来组织 skills，而不是按功能。具体来说分四组：
规划阶段：需求拆解、技术方案设计、任务拆分。编码阶段：代码生成、代码审查、重构建议。测试阶段：测试生成、测试运行、覆盖率分析。交付阶段：提交信息生成、PR 描述生成、变更日志生成。
这样组织的好处是，AI 在不同阶段能快速找到对应的技能组，不会在编码时去加载测试相关的 skill。
6.2 用 skill 固化团队规范
这是 skills 最有价值的应用场景之一。每个团队都有自己的规范，但规范文档写出来没人看，AI 更不会主动遵守。把规范做成 skill，AI 在干活时自动遵守，效果立竿见影。
比如你们团队的提交信息规范是 Conventional Commits，那就做一个commit-messageskill，里面写清楚格式、类型枚举、示例。以后 AI 生成提交信息时，自动就符合规范了。
再比如你们的 API 设计规范、数据库命名规范、日志格式规范，都可以做成 skill。新成员加入时，不用花一周时间读文档，AI 直接带着规范干活。
6.3 skill 的测试和迭代
skill 也需要测试。我的做法是建一个skill-tests目录，里面放一些典型的用户输入，然后手动跑一遍，看 AI 的行为是否符合预期。
比如测试code-reviewskill，我会准备三段代码：一段有明显 bug 的、一段有性能问题的、一段没问题的。然后分别让 AI 审查，看它能不能准确识别。
迭代节奏上，我一般每两周回顾一次 skill 的使用情况。哪些经常触发、哪些从不触发、哪些触发后效果不好，根据实际情况调整。skill 不是写完就完事的，它需要像代码一样维护。
6.4 跨工具复用的现实考量
很多人问能不能一套 skill 在 Claude Code、Codex、Cursor 之间通用。现实是：核心内容可以复用，但需要适配层。
SKILL.md的正文部分基本是通用的，因为都是自然语言指令。差异主要在 frontmatter 字段和加载机制上。我的做法是维护一份“源 skill”，然后用脚本生成各平台需要的格式。这样改一处，处处更新。
热搜里vscode配置claude code、claude code for vs code、idea使用skills这些词说明大家在不同 IDE 里用这些工具。好消息是 skills 本身和 IDE 关系不大，它依赖的是 AI 工具本身，不是编辑器。所以你在 VS Code 里配好的 skill，换到 IDEA 里只要 AI 工具一样，skill 照样能用。
6.5 我个人的一些使用心得
用了大半年 skills，最大的感受是：它把 AI 编程从“对话”变成了“协作”。以前是我说一句 AI 做一步，现在是我定义好规则和技能，AI 自己按规则干活。这个转变带来的效率提升是数量级的。
另一个感受是：写 skill 的过程，其实是在梳理你自己的知识。很多时候你以为自己很清楚某个流程，但真要写成 skill 时才发现有很多模糊地带。这个过程逼你把隐性知识显性化，对个人成长也有好处。
最后一个建议：从一个小 skill 开始，别一上来就搞大而全的体系。先做一个你每天都要重复交代的事情，把它变成 skill，用一周，感受一下效果。有感觉了再扩展。skills 这东西，用起来比看起来简单，但用好需要时间打磨。
如果你现在还在纠结claude code安装、codex安装这些基础问题，我的建议是先装好工具，跑通一个最简单的 skill，再逐步深入。工具是死的，skill 是活的，把精力花在打磨 skill 上，回报率最高。
