1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题很多人会懵——这词太泛了。但结合热搜词里高频出现的 Claude Code、Codex、agents、plugin 这几个词方向其实很明确这里说的 skills指的是 AI 编程助手尤其是 Claude Code、Codex 这类 agent 工具里的技能扩展机制。它不是传统意义上的插件市场里点一下安装那么简单而是一套让 agent 具备特定领域能力的配置体系。我接触这套东西的起点很偶然。当时用 Claude Code 处理一个前端项目发现它默认对某些框架的写法理解得不够细生成的代码总差那么点意思。后来才知道可以通过 skills 把项目约定、代码规范、常用模式喂给 agent让它在这个项目里表现得更像一个熟悉业务的老手。这个发现直接改变了我用 AI 编程工具的方式。所以这篇内容想聊清楚几件事skills 的本质是什么、它和 plugin/agent 的关系、怎么从零搭一套能用的 skills、以及我在实际配置中踩过的那些坑。适合已经在用 Claude Code 或 Codex、但还没深入折腾过扩展机制的人也适合想搞清楚AI 编程助手到底能定制到什么程度的观望者。不需要你有多深的底层知识但最好已经跑通过一次基本的 agent 对话流程不然有些概念会悬空。需要先说明一点skills 这个概念在不同工具里叫法不完全一样Claude Code 里偏向技能/指令集Codex 生态里更多和 agent 配置绑定社区里还有人把它和 plugin 混着说。我下面会尽量用统一的视角来讲但遇到具体工具差异时会点明。2. skills 和 plugin、agent 到底是不是一回事2.1 三个概念的真实边界刚接触时我最大的困惑就是skills、plugin、agent 这三个词老是一起出现到底谁包含谁后来理清楚了一个大致的关系agent是执行主体是那个会思考、会调工具、会多轮对话的东西。Claude Code、Codex 本身就是一个 agent 运行时。plugin偏向接入能力比如让 agent 能读某个数据库、能调某个外部服务、能操作某个 IDE。它解决的是agent 能碰到什么。skills偏向行为知识是告诉 agent在这个场景下应该怎么做的指令、范例、约束集合。它解决的是agent 知道怎么做才对。打个比方agent 是一个新来的工程师plugin 是给他开的系统权限和账号skills 则是你递给他的那本《本项目开发规范》。三者缺一不可但职责完全不同。很多人配置失败就是因为把 skills 当 plugin 装或者指望 plugin 能顺便教会 agent 业务逻辑。2.2 为什么 skills 值得单独折腾有人会问我直接在对话里把要求说清楚不就行了为什么要搞一套 skills我自己的体会是一次性对话和持久化技能是两码事。对话里说的要求下一轮可能就忘了或者被新的上下文冲淡。而 skills 是写进配置、每次会话都会加载的相当于给 agent 装了一个默认行为基线。尤其是团队协作场景你把规范写成 skills所有人用的 agent 行为一致产出的代码风格才稳定。我试过在一个多人项目里不写 skills结果每个人调出来的 agent 生成风格五花八门review 的时候头都大了。另外skills 还能承载一些隐性知识——比如某个内部库的特殊用法、某个接口的坑、某段历史遗留代码不能碰的原因。这些写进 skills比每次口头交代靠谱得多。2.3 一个容易混淆的点skills 不是越多越好我一开始犯的错就是贪多恨不得把所有规范都塞进 skills。结果 agent 加载一堆指令后反而变得畏手畏脚简单任务也要绕一大圈。后来才明白skills 应该聚焦在高频、易错、有明确约定的地方而不是把整个 wiki 搬进去。这个度后面会细讲。3. 一套能用的 skills 该包含哪些内容3.1 项目上下文让 agent 先认识环境skills 的第一层是让 agent 知道自己在什么项目里。这部分通常包括技术栈、目录结构约定、构建命令、测试命令。比如你告诉它这是一个用 Vite 构建的 React 项目组件放在 src/components测试用 Vitest它后续生成的文件路径和命令就不会乱来。我实测下来光是把构建和测试命令写清楚就能省掉大量agent 跑错命令然后卡住的时间。之前没写的时候它老是用 npm run build而我项目实际用的是 pnpm来回纠正特别烦。3.2 代码规范把 review 意见前置第二层是代码风格和规范。缩进、命名、import 顺序、注释要求、错误处理模式这些都可以写进去。关键是别写成抽象口号要给具体例子。比如不要写注意错误处理而是写所有异步调用必须用 try/catch 包裹catch 里用 logger.error 记录不要直接 console.log。我踩过的坑是规范写得太抽象agent 理解不了生成的东西还是老样子。后来改成反例 正例的写法效果立竿见影。下面是一个简化示例## 错误处理规范 反例 const data await fetchData(); // 没有错误处理 正例 try { const data await fetchData(); } catch (err) { logger.error(fetchData failed, err); throw new AppError(DATA_FETCH_FAILED); }3.3 领域知识内部库和特殊约定第三层是最有价值的也是最难写的——内部库用法、接口约定、历史包袱。这部分往往是新人最容易踩坑的地方写进 skills 相当于给 agent 也做了一次 onboarding。比如我们有个内部请求库默认会重试三次但某些幂等性敏感的接口必须关掉重试。这种知识不写下来agent 生成的代码就会埋雷。我把它写成一条明确的规则后再没出现过相关问题。3.4 任务模式常见操作的配方第四层是任务模板。比如新增一个页面应该改哪几个文件、新增一个 API要走哪些步骤。这类配方能让 agent 在处理常见任务时直接照做不用每次重新推理。我一般会把这类内容写成有序步骤配上文件路径。实测下来agent 执行这类有明确配方的任务时成功率明显高于让它自由发挥。4. 从零搭一套 skills 的完整过程4.1 先确定 skills 的存放位置和加载方式不同工具的 skills 存放位置不一样。Claude Code 一般放在项目根目录的特定配置目录下Codex 生态里则可能和 agent 配置文件放一起。我建议第一步先查清楚你用的工具从哪个路径加载 skills别写完发现根本没被读到。一个通用做法是在项目根目录建一个专门的配置目录把 skills 按主题拆成多个文件而不是全塞一个巨大的文件。拆开的好处是维护方便也方便按需加载。我现在的习惯是按上下文规范领域知识任务模板分成四个文件。4.2 用最小可用集起步别一上来就写全我强烈建议第一版只写最核心的几条技术栈、构建命令、一条最重要的代码规范。先跑起来看 agent 的行为有没有变化。确认加载生效后再逐步往里加。原因很简单如果一次写太多出了问题你根本不知道是哪条规则导致的。最小集起步每次只加一块出问题好定位。这个思路和调参是一样的变量要一个一个改。4.3 验证 skills 是否真的生效写完不代表生效。验证方法有几个一是故意让 agent 做一个违反规范的操作看它会不会被拉回来二是直接问它你知道本项目的构建命令是什么吗看它答得对不对。我常用的一个技巧是在 skills 里写一条非常具体的、平时不会出现的规则比如所有日志必须带 [APP] 前缀然后让 agent 生成一段日志代码看它有没有加前缀。加了就说明加载成功验证完再把这条测试规则删掉。4.4 迭代把每次纠正都沉淀回 skillsskills 不是一次写完就完事的。我的做法是每次在对话里纠正了 agent 的一个行为如果这个纠正具有普遍性就把它补进 skills。这样 skills 会随着使用越来越贴合你的项目。这个习惯坚持下来你会发现需要口头纠正的次数越来越少。本质上你是在把临时指令逐步转化为永久能力。5. 实测中那些让人抓狂的坑5.1 skills 写了但没生效先查加载路径最常见的坑就是写完没反应。九成情况是路径不对或者文件格式不对。有些工具要求特定扩展名有些要求特定的头部标记。我建议先用一个极简的 skills 文件测试加载确认机制通了再写内容。还有一种情况是缓存。有些工具会缓存 skills改了文件但没重新加载。这时候重启一下会话或者清一下缓存通常能解决。5.2 规则冲突两条 skills 打架当你 skills 写多了很容易出现规则冲突。比如一条说用箭头函数另一条说用 function 声明。agent 遇到冲突时行为会变得不稳定有时这样有时那样。我的处理方式是定期 review skills把重复和冲突的合并掉。另外给规则分优先级明确当 A 和 B 冲突时以 A 为准。这个优先级机制在复杂项目里特别重要。5.3 指令太长导致 agent注意力涣散前面提过skills 不是越多越好。我实测过一个极端情况skills 写到几千行后agent 对其中靠后的规则几乎视而不见。这大概率是上下文长度和注意力分配的问题。解决办法是分层核心规则放最前面且精简细节规则拆到单独文件按需引用。别指望 agent 能记住一本字典。5.4 跨工具迁移skills 不能直接复制Claude Code 的 skills 和 Codex 的 skills 格式往往不兼容。我试过直接把一套配置从 A 工具搬到 B 工具结果完全没生效。后来老老实实按目标工具的格式重写了一遍。所以如果你同时用多个工具建议维护一份源知识然后针对每个工具生成对应格式。虽然麻烦但比每次重写强。5.5 团队协作skills 要进版本控制这个不算坑但很容易被忽略。skills 应该和代码一起进 git这样团队所有人共享同一套配置。我见过有人把 skills 放在本地不提交结果只有他自己用着爽别人一脸懵。进版本控制还有个好处skills 的变更可以 review可以追溯。哪次改动导致 agent 行为变差一查就知道。6. 让 skills 真正提升效率的几个进阶思路6.1 按任务类型拆分 skills而不是按知识类型一开始我按规范知识这种知识类型拆文件后来发现按任务类型拆更实用。比如前端页面开发 skills后端接口 skills数据处理 skills每个任务类型下把相关的上下文、规范、模板都放一起。这样 agent 处理某类任务时加载的就是一个完整的能力包。6.2 给 skills 加触发条件有些工具支持条件加载 skills比如只在处理特定文件类型时才加载某套规则。这个机制能有效控制上下文长度。如果你的工具支持强烈建议用起来。不支持的话也可以通过文件命名和引用关系来模拟。6.3 把失败案例写进 skills除了正面规范反面案例也很有价值。我会把一些曾经踩过的坑写成明确的禁止项比如不要用 XX 库的 YY 方法它在 ZZ 场景下会出问题。这类规则往往比正面规范更能防止事故。6.4 定期清理删掉过时的 skills项目在演进skills 也会过时。我一般每个季度 review 一次把不再适用的规则删掉。留着过时规则不仅没用还可能误导 agent。清理这件事和清理代码里的死代码一样重要。6.5 用 skills 承载决策记录有些技术选型背后的原因代码里看不出来但很重要。比如为什么这个模块不用某个流行库这种决策记录写进 skills能让 agent 在生成相关代码时避开已经被否决的方案。这相当于把架构决策文档和 agent 能力打通了。7. 关于 skills 生态的一些观察现在围绕 Claude Code、Codex 这些工具的 skills 生态正在快速长起来社区里能看到各种skills 推荐好用的 skills分享。我的看法是别人的 skills 可以参考但别直接照搬。因为 skills 高度依赖具体项目和团队约定别人的规范放到你项目里很可能水土不服。更靠谱的做法是看别人 skills 的结构和写法学他们怎么组织规则、怎么给例子、怎么处理冲突然后结合自己项目重写。结构和方法论是可以迁移的具体内容不行。另外skills 这个方向本身还在快速变化工具格式、加载机制、能力边界都可能变。所以别把 skills 写得太依赖某个工具的特定语法尽量把知识和格式分开这样工具升级时迁移成本低。我在实际使用中最大的体会是skills 的价值不在于写得多全而在于写得准。一条精准的规则胜过十条模糊的口号。而且 skills 是需要养的用得越久、迭代越多它才越贴合你的项目。刚开始别追求完美先跑起来然后在使用中慢慢打磨这才是最实际的路子。