1. 从“skills”这个词说起：它到底在解决什么问题
第一次看到“skills”这个标题，很多人会以为是某个泛泛的能力清单，或者又一篇讲“程序员该具备哪些软技能”的鸡汤。但结合热搜词里的 Claude Code、Codex、plugin、agents 来看，这里的 skills 指向的是一个非常具体的东西：给 AI 编程助手（agent）挂载可复用的能力模块。你可以把它理解成给一个刚入职的实习生配一本“操作手册 + 工具箱”，手册告诉他遇到什么情况该翻哪一页，工具箱里放着他干活要用的家伙事。
我最早接触这个概念是在折腾 Claude Code 的时候。当时我的诉求很朴素：每次让 AI 帮我写代码，它都要重新理解我的项目结构、我的代码规范、我的提交习惯，重复劳动太多。后来发现社区里已经有人在用 skills 这套机制，把“项目约定”“常用命令”“领域知识”打包成一个个独立模块，agent 在需要的时候自动加载。这一下就把重复沟通的成本砍掉了一大半。
所以这篇内容我想聊的不是“skills 是什么”这种百科式定义，而是一个一线开发者怎么理解、搭建、调试、维护自己的 skills 体系。适合三类人看：一是刚上手 Claude Code 或 Codex、还在摸索怎么让 AI 更懂自己项目的人；二是已经用过一段时间、但 skills 越堆越乱、想理清架构的人；三是想自己开发 skills 分享给别人、或者从社区找现成 skills 来用的人。不管你是哪一类，下面这些从实操里抠出来的细节，应该都能对上你的痛点。
需要先说明一点：skills 这套东西目前在不同工具里的叫法和实现细节不完全一样，Claude Code 有它自己的一套，Codex 也有对应的机制，社区里还有各种第三方 plugin 市场。我不会假装它们完全统一，而是尽量讲清楚共通的设计思路，再针对具体工具补差异。你读完应该能自己判断：手上这个工具该怎么配、这个 skill 该不该装、装完出问题该往哪查。
2. skills 的整体设计思路：为什么是“模块”而不是“大提示词”
2.1 从“一坨超长 system prompt”到“按需加载的能力包”
早期大家让 AI 懂项目，最直接的办法就是把所有要求塞进一个超长的 system prompt 或者项目级配置文件里。我试过，一开始挺爽，写个两三百行，把代码风格、目录结构、禁用库、提交规范全写进去。但很快就出问题了：上下文是有预算的。你塞得越多，留给真正代码和对话的空间就越少；而且很多规则是场景相关的，写接口的时候用不上前端样式规范，改数据库 migration 的时候也不需要知道组件命名约定。全都常驻，纯属浪费。
skills 的核心设计就是解决这个浪费。它把能力拆成一个个独立模块，每个模块有自己的触发条件——可能是你说了一句话，可能是 agent 判断当前任务类型匹配，也可能是你手动调用。只有被触发时，这个模块的内容才进入上下文。这跟传统编程里的“按需 import”是一个思路，只不过 import 的是知识和工具，而不是代码。
提示：不要一上来就把所有东西都做成 skill。先观察自己一周内反复跟 AI 解释的内容是什么，那些才是真正值得沉淀的。
2.2 skill、plugin、agent 三者的关系别搞混
热搜词里这三个词经常一起出现，但它们是不同层级的东西，混着理解会越看越晕。我用自己的话给个区分：
- agent是干活的“人”，它负责理解你的意图、决定调用什么、执行任务。Claude Code、Codex 本身就是一个 agent 或者 agent 的运行环境。
- skill是这个人掌握的“一项技能”，是一份结构化的知识或一组操作说明。它告诉 agent“遇到这类事该怎么做”。
- plugin更像是“安装包”或“扩展”，它可能包含一个或多个 skill，也可能包含命令、配置、脚本等。你从市场下载一个 plugin，里面可能打包了好几个 skill。
打个比方：agent 是厨师，skill 是菜谱，plugin 是整本菜谱合集或者一套厨具套装。你请了个厨师（agent），给他一本川菜菜谱（skill），他就能做川菜；你给他一整套包含菜谱和专用刀具的套装（plugin），他能做的事就更多。理解这个层级，后面配置的时候就不会把“装插件”和“写技能”当成一回事。
2.3 为什么社区会形成“skills 市场”这种生态
热搜里出现了“claude 国内安装 skills 官方市场”“skills 下载平台有哪些”“find skills”这类词，说明已经形成了分发生态。这背后的逻辑很自然：skills 是纯文本为主的结构化内容，天然容易分享和复用。一个人写好了“React 项目代码审查 skill”，另一个人直接拿来改改就能用，边际成本极低。
但生态一热闹，问题也来了：质量参差不齐。我见过一些 skill 写得又长又空，全是“请写出高质量代码”这种废话，装上去除了占上下文没有任何作用。所以后面我会专门讲怎么判断一个 skill 值不值得装、怎么自己写一个真正有用的。
3. 核心细节拆解：一个 skill 到底由什么构成
3.1 触发描述：决定 skill 会不会被用上的关键
一个 skill 最核心的部分不是里面的内容，而是它什么时候被激活。这部分通常是一段描述，agent 会拿它跟当前任务做匹配。我踩过最大的坑就在这里：早期我写的触发描述太模糊，比如“用于处理前端相关任务”，结果要么永远不触发，要么什么前端任务都触发，把上下文塞满。
好的触发描述应该具体到任务类型 + 技术栈 + 动作。举个例子对比：
| 差的触发描述 | 好的触发描述 |
|---|---|
| 处理前端任务 | 当用户要求新增或修改 React 函数组件、涉及 hooks 使用时激活 |
| 数据库相关 | 当需要编写或修改 PostgreSQL 的 migration 文件、涉及表结构变更时激活 |
| 代码规范 | 当用户要求 review 代码或提交前检查命名与目录结构时激活 |
右边这种写法，agent 匹配起来准确率高很多。原理很简单：匹配本质上是语义相似度计算，描述越具体，向量空间里它跟目标任务的“距离”就越近，跟无关任务的距离就越远。
3.2 内容主体：知识型还是操作型
skill 的内容大致分两类，写法完全不同。
知识型 skill主要传递“事实和约定”，比如“我们这个项目所有 API 返回都用统一的 Result 包装”“日期一律用 UTC 存储”。这类内容用清晰的条目写就行，重点是准确、无歧义。
操作型 skill传递的是“步骤和流程”，比如“如何新增一个数据库表”“如何发布一个版本”。这类要写成有序步骤，每一步说清楚输入、动作、预期输出。我建议操作型 skill 里尽量给出可直接复制的命令或代码片段，因为 agent 执行时最怕模糊指令。
注意：操作型 skill 里涉及删除、覆盖、发布这类不可逆动作时，一定要显式写明“执行前需向用户确认”，否则 agent 可能一路执行到底，后果自己承担。
3.3 边界与例外：最容易被忽略但最值钱的部分
大部分 skill 只写了“该怎么做”，没写“什么情况下不该这么做”。而实际项目里，例外情况往往才是最容易出错的。比如一个“统一用 Result 包装返回值”的 skill，如果不写明“流式接口和文件下载接口除外”，agent 可能真的给文件下载套一层 JSON 包装，直接坏掉。
我在自己的 skill 里专门留了一节叫“例外与禁忌”，列清楚哪些场景不适用、哪些操作绝对不能做。这一节通常是整个 skill 里信息密度最高、最省事的部分。写的时候可以问自己：上次 AI 在这件事上犯错是什么情况？把那个情况写进去。
3.4 版本与依赖：skill 也会过期
技术栈会升级，框架 API 会变，一个去年写的 skill 今年可能就给出过时建议了。所以成熟的 skill 应该标注适用的版本范围，比如“适用于 React 18+”“适用于 Python 3.10 以上”。如果 skill 依赖某个外部工具或命令，也要写清楚依赖项。
我维护自己那套 skill 时，养成了一个习惯：每次升级主要依赖后，回头扫一遍相关 skill，把过时的部分改掉。这件事不做，skill 就会从“帮手”慢慢变成“坑”。
4. 实操：从零搭建一套自己的 skills 体系
4.1 环境准备与工具选择
先明确你用的是哪个 agent 环境。Claude Code 和 Codex 的 skill 加载机制有差异，配置文件的路径和格式也不一样。我这边以通用的思路来讲，具体路径你按自己工具的文档对一下。
大致流程是：找到工具约定的 skill 存放目录（通常在项目根目录下的某个隐藏文件夹，或者用户级配置目录），把 skill 文件按约定格式放进去，然后在配置里声明或让它自动扫描。有些工具支持项目级 skill（只对当前项目生效）和用户级 skill（对所有项目生效），我建议项目强相关的放项目级，通用工作习惯放用户级，这样换项目时不会带着一堆无关规则。
如果你是从社区市场安装 plugin，一般会有对应的安装命令，装完检查一下它到底往哪个目录写了什么文件，别装完不知道东西在哪。
4.2 写第一个 skill：以“新增 API 接口”为例
我拿一个真实场景走一遍。假设我的项目是 Node.js + Express，每次新增接口都有一套固定流程。我把它写成一个操作型 skill。
触发描述我这样写：“当用户要求新增、修改或删除 HTTP API 接口，涉及路由、控制器、参数校验时激活。”
内容主体分几块：
- 文件位置约定：路由文件放
src/routes/，控制器放src/controllers/，两者文件名保持一致。 - 标准步骤：先建路由文件，再建控制器，然后在
src/routes/index.js注册，最后补一个最小测试。 - 参数校验：所有入参必须经过校验中间件，禁止直接在控制器里读
req.body原始值。 - 返回格式：统一用
{ code, data, message }结构。 - 例外：文件上传和流式响应接口不走统一返回格式。
写完放进项目级 skill 目录，重启 agent 环境，然后测试：让它“新增一个查询用户列表的接口”，看它是否按这套流程走。第一次大概率会有偏差，根据偏差回去改 skill 描述或内容，迭代两三轮基本就稳了。
4.3 参数与配置的取舍逻辑
skill 里经常要写一些“阈值”或“默认值”，比如“函数超过多少行要拆分”“单个文件超过多少行要警告”。这些数字不是拍脑袋来的，我给个我自己的推导方式。
以函数长度为例：我统计过自己项目里维护性最好的那批函数，平均在 20 到 40 行之间；超过 60 行的函数，出 bug 的概率明显上升。所以我在 skill 里写“函数建议不超过 50 行，超过时提示考虑拆分”。这个 50 是从实际数据里来的，不是抄的。你也可以统计一下自己项目的历史数据，得出适合自己团队的阈值。skill 里的数字最好都有依据，否则 agent 执行起来会显得很机械。
4.4 调试 skill 是否生效的三种方法
skill 写完不生效是常态，别慌。我一般按这三步排查：
- 第一步，确认加载：看 agent 启动日志或相关命令输出，确认它扫描到了你的 skill 文件。路径错、格式错是最常见的原因。
- 第二步，确认触发：故意说一句明显该触发的话，观察 agent 行为有没有变化。如果没变化，多半是触发描述写得太偏。
- 第三步，确认内容：如果触发了但行为不对，那就是内容本身的问题，逐条对照它实际做的和 skill 里写的差在哪。
这三步能把问题定位到具体环节，比盲目改要快得多。
5. 常见问题与排查技巧实录
5.1 skill 装了但完全不触发
这是最高频的问题。原因通常有三个：路径不对、格式不符合工具要求、触发描述太模糊。我遇到过一次，折腾半天发现是文件扩展名不对，工具只认特定后缀。所以第一件事永远是对照官方文档确认文件位置和命名规范。
还有一个隐蔽原因：skill 之间触发条件冲突。如果你装了两个 skill，描述都覆盖“代码审查”，agent 可能只激活其中一个，或者两个都激活导致内容打架。这时候要么合并，要么把触发条件写得更精确，让它们各管各的。
5.2 多个 skill 内容互相矛盾
项目做大了，skill 多了，矛盾几乎必然出现。比如一个 skill 说“日志用英文”，另一个说“日志用中文”。agent 遇到这种冲突，行为会变得随机。
我的处理办法是建立优先级规则：在项目级配置里明确哪类 skill 优先。或者更彻底一点，定期做一次 skill 审计，把重复和矛盾的合并掉。我一般一个月扫一次，删掉不再用的，合并重叠的，修正过时的。这件事花不了多少时间，但能避免很多莫名其妙的错误。
5.3 上下文被 skill 撑爆
有些 skill 内容特别长，一触发就吃掉大量上下文，导致 agent 处理真正任务时“脑子不够用”。判断方法很简单：如果触发某个 skill 后，agent 的回答质量明显下降、开始遗忘前面的对话，那多半是上下文压力太大了。
解决办法是拆分。一个 800 行的 skill 拆成三个 200 多行的，各自有独立触发条件，按需加载。另外，skill 里能引用外部文件就别全塞正文，让 agent 需要时再去读。
5.4 从社区下载的 skill 水土不服
社区 skill 是别人按自己的项目写的，直接拿来用经常不匹配。我的做法是先读再改：读一遍它的触发条件和内容，把跟自己项目不符的部分改掉，尤其是路径、命令、命名规范这些强绑定的东西。别指望下载下来就能直接用，那跟买别人的衣服不试穿就穿是一个道理。
下面这张表是我整理的常见问题速查，遇到问题可以先对一下：
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 完全不触发 | 路径/格式错误 | 查加载日志、对文档 |
| 触发但行为不对 | 内容描述有歧义 | 逐条对照实际行为 |
| 多个 skill 打架 | 触发条件重叠 | 精确化描述或合并 |
| 回答质量下降 | 上下文超载 | 拆分 skill、外置引用 |
| 建议过时 | skill 未随依赖更新 | 定期审计、标注版本 |
5.5 几个我踩过的坑
第一个坑：把 skill 当文档写。我一开始写了一大段背景介绍，结果 agent 根本不看背景，只看操作步骤。后来我把背景压缩成一句话，把步骤写详细，效果好很多。
第二个坑：触发描述用否定句。比如“不用于测试相关任务”，这种否定描述匹配效果很差，agent 经常还是触发。正确做法是只写正向的适用场景，把不适用的场景放到内容里的“例外”一节。
第三个坑：skill 里写死绝对路径。换台机器就废了。能用相对路径就用相对路径，必须用绝对路径的地方标注清楚需要用户自己改。
6. 进阶：让 skills 体系真正长期可用
6.1 建立 skill 的命名与分类规范
skill 一多，找起来就费劲。我给自己定了一套命名规则：领域-动作-对象，比如api-create-endpoint、db-write-migration、review-check-naming。这样光看文件名就知道它管什么。分类上我按“项目约定”“操作流程”“领域知识”三类分目录，找的时候先想类别再找具体。
6.2 定期审计与迭代节奏
我现在的节奏是：每周花十分钟看一遍这周 agent 犯的错，判断哪些是 skill 缺失或过时导致的，顺手补上或改掉。每月做一次全量扫描，删冗余、合并重复。这个习惯坚持下来，skill 体系会越来越贴合自己的实际工作，而不是越堆越乱。
6.3 分享与复用：什么时候值得开源自己的 skill
如果你写的某个 skill 解决的是通用问题，比如“FastAPI 项目标准结构”，那它可能对别人也有用，可以考虑整理后分享。但分享前一定要去掉项目私有信息：内部路径、私有包名、公司特定规范。我见过有人直接把带内部信息的 skill 发出去，虽然大多无害，但总归不专业。
反过来，看到别人的 skill 时，也别无脑装。先看它的触发描述是否清晰、内容是否有具体步骤、有没有标注版本和依赖。一个连触发条件都写得含糊的 skill，大概率内容也一般。
6.4 一个我常用的自检清单
每次写完或改完一个 skill，我会过一遍这几个问题：
- 触发描述是否具体到任务类型和技术栈？
- 内容里有没有可直接执行的步骤或命令？
- 有没有写明例外和禁忌？
- 有没有标注适用版本和依赖？
- 有没有写死路径或私有信息？
- 跟现有 skill 有没有冲突？
这六个问题过一遍，基本能过滤掉大部分低级问题。skill 这东西，写得好是杠杆，写得差是负担，区别就在这些细节里。
最后分享一个我自己的小习惯：我会在项目根目录放一个skills-notes.md，记录每个 skill 的用途、最后修改时间和修改原因。过几个月回头看，能快速想起当初为什么这么写，避免重复踩同一个坑。这个文件不参与 agent 运行，纯粹给自己看的，但省下的时间远超维护它的成本。
