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 运行纯粹给自己看的但省下的时间远超维护它的成本。