1. 从“skills”这个词说起它到底在解决什么问题第一次看到“skills”这个标题很多人会以为是某个泛泛的能力清单或者又一篇讲“如何提升自己”的鸡汤。但如果你最近在折腾 Claude Code、Codex、各类 agents 框架就会发现这个词已经变成了一个非常具体的工程概念——它指的是给 AI 编程助手挂载的可复用能力包。你可以把它理解成给一个刚入职的实习生配的一套“标准作业程序”不是重新训练他而是告诉他遇到什么场景该翻哪本手册、调哪个工具、按什么格式输出。我最早接触这个概念是在给团队搭内部编码助手的时候。当时最大的痛点是每次开新会话都要把项目规范、目录结构、常用命令、代码风格重新讲一遍讲完还经常被忽略。后来把这一整套东西抽成一个独立的 skills 目录让助手在需要的时候自己去读效果立刻不一样了。所以这篇内容我想聊的不是“skills 是什么”这种定义题而是一个能真正落地的 skills 体系该怎么设计、怎么组织、怎么和 Claude Code / Codex 这类工具配合。不管你是刚装好 Claude Code 的新手还是已经在用 agents 做自动化流程的老手下面这些内容应该都能直接抄作业。需要先说明一点skills 目前在不同工具里的实现细节不完全一样。Claude Code 有它自己的 skills 机制Codex 侧更多是通过配置和上下文注入来模拟类似效果社区里也有大量第三方 plugin 在做这件事。我下面讲的是跨工具通用的设计思路具体到某个工具的配置我会单独标出来。2. skills 的整体设计思路为什么不能写成一个大文件2.1 核心矛盾上下文窗口是稀缺资源很多人第一次做 skills直觉就是把所有规范、示例、命令全写进一个SKILLS.md然后让助手每次启动都读一遍。我试过结果是灾难性的。原因很简单上下文窗口是稀缺资源。你塞进去五千字的规范助手真正用来理解当前任务的空间就被压缩了而且大量无关内容会稀释注意力导致它抓不住重点。正确的思路是按需加载、分层组织。就像你不会把整本员工手册背下来再去干活而是遇到报销问题时才去翻报销那一章。skills 的设计目标应该是平时不占地方需要时能精准命中。2.2 分层结构入口、索引、具体技能我目前用的结构是这样的实测下来在 Claude Code 和 Codex 里都跑得通skills/ ├── INDEX.md # 入口只写“什么场景看哪个文件” ├── coding-style.md # 代码风格规范 ├── api-conventions.md# 接口约定 ├── debug-playbook.md # 排查问题的标准流程 ├── deploy.md # 部署相关命令和注意事项 └── examples/ ├── crud.md # 增删改查的参考实现 └── auth.md # 鉴权模块的参考实现INDEX.md是整个体系的入口它必须足够短短到可以常驻上下文。我一般控制在 300 字以内只做一件事建立“场景 → 文件”的映射。比如# Skills Index - 写新接口前先读 api-conventions.md - 改样式或组件结构先读 coding-style.md - 遇到报错不知道怎么查读 debug-playbook.md - 要发布版本读 deploy.md - 需要参考实现去 examples/ 找对应模块这样助手在接到任务时会先判断场景再去读对应的文件而不是一次性把所有内容灌进去。2.3 为什么用 Markdown 而不是 JSON 或 YAML有人会问为什么不把 skills 写成结构化的 JSON方便程序解析我的经验是skills 的主要消费者是语言模型不是程序。Markdown 的标题层级、列表、代码块恰好是模型最容易理解的格式。JSON 虽然机器友好但模型读起来反而容易丢失语义尤其是嵌套深的时候。而且 Markdown 对人也可读你调试的时候直接打开就能看不用额外工具。提示如果你的 skills 需要被程序自动加载比如某些 plugin 机制可以在 Markdown 前面加一段 YAML front matter 做元数据正文仍然用 Markdown。这样两边都兼顾。3. 核心细节解析一个高质量 skill 文件该长什么样3.1 开头必须写清楚“触发条件”我见过太多 skill 文件上来就是一大段规范但没写“什么时候该用我”。结果助手要么不用要么乱用。所以每个 skill 文件的第一段我强制要求写清楚触发条件。比如debug-playbook.md的开头# Debug Playbook 当出现以下情况时使用本文件 - 运行时报错且错误信息不明确 - 测试失败但原因不清楚 - 行为与预期不符需要系统性排查 不适用语法错误、拼写错误这类一眼能看出的问题。这段“不适用”很重要它帮助手排除掉简单场景避免小题大做。3.2 步骤要可执行不要写原则“代码要写得清晰易读”这种话写了等于没写。skill 里的内容必须是可执行的动作。对比一下差的写法好的写法注意错误处理所有异步调用必须用 try/catch 包裹catch 里至少记录 error.message 和调用栈保持命名一致组件文件用 PascalCase工具函数用 camelCase常量用 UPPER_SNAKE_CASE写好注释每个导出函数上方写一行说明用途参数复杂时补充 param右边这种写法助手读完就能直接照做不需要再“理解”你的意图。3.3 用示例代替描述语言模型对示例的敏感度远高于抽象描述。与其写“接口返回要统一格式”不如直接给一个示例// 成功 { code: 0, data: {...}, message: ok } // 失败 { code: 40001, data: null, message: 参数校验失败 }一个示例顶十句描述这是我踩了很多坑之后最深的体会。3.4 控制单个文件的长度单个 skill 文件我建议控制在500 到 1500 字之间。太短说明信息量不够太长说明你没拆干净。如果一个主题超过 1500 字就说明它应该拆成多个文件或者把细节挪到examples/里。比如api-conventions.md只写约定具体某个接口怎么实现放到examples/对应文件里。注意不要为了“完整”而堆砌内容。skills 的价值在于精准不在于全面。一个 800 字但每句都有用的文件胜过一个 3000 字但一半是废话的文件。4. 实操过程从零搭一套 skills 并接入 Claude Code4.1 第一步梳理你真正重复讲的东西打开你最近十次和助手的对话记录把那些你反复解释的内容列出来。我当初列出来的大概有项目目录结构、代码风格、接口返回格式、常用命令、部署流程、排查步骤。这六项就是我的第一批 skill 文件。这一步的关键是基于真实重复而不是想象。很多人一上来就想搭一个“完美体系”结果写了几十个文件实际用到的没几个。先解决最痛的那几个用起来再迭代。4.2 第二步写 INDEX.md 并控制长度INDEX.md 我反复改过很多版最后稳定下来的原则是每条映射不超过一行总行数不超过 15 行。超过就说明你的 skill 粒度太细需要合并。# Skills Index - 新接口开发读 api-conventions.md参考 examples/crud.md - 组件开发读 coding-style.md - 排查问题读 debug-playbook.md - 发布上线读 deploy.md - 不确定读哪个先读本文件再决定最后一条“不确定读哪个”是给助手的一个兜底指令避免它在场景模糊时乱猜。4.3 第三步在 Claude Code 里挂载 skillsClaude Code 的 skills 机制核心是让它在启动时读取你的 INDEX.md然后按需读取其他文件。具体做法是在项目根目录放一个约定位置的文件不同版本路径可能不同我目前用的是项目根目录下的.claude/skills/然后在项目说明里告诉它本项目使用 skills 体系。开始任务前先读 .claude/skills/INDEX.md 根据场景决定是否需要读取其他 skill 文件。实测下来这句话必须写清楚否则助手不一定会主动去读。我试过只放文件不写说明结果它完全忽略。写清楚之后命中率明显提升。4.4 第四步在 Codex 侧做类似配置Codex 没有 Claude Code 那样原生的 skills 目录约定但可以通过在项目根目录放AGENTS.md或类似说明文件来达到类似效果。我的做法是把 INDEX.md 的内容精简后放进AGENTS.md的开头然后指向 skills 目录# 项目说明 本项目使用 skills 体系详见 skills/INDEX.md。 开始任务前先读 INDEX.md按场景加载对应 skill。Codex 读取项目说明文件的行为比较稳定所以这一步基本能保证 skills 被纳入上下文。4.5 第五步验证与迭代搭好之后我会做一轮验证给它一个典型任务看它是否读了正确的 skill 文件。验证方法很简单在 skill 文件里放一句特殊标记比如“如果你读到了这里请在回复开头写 [SKILL:debug]”然后看它有没有写。这个方法有点土但非常有效能直接看出加载是否命中。迭代的节奏我建议是每周回顾一次这周有哪些任务它没按规范做是 skill 没写清楚还是 INDEX 映射不对针对性修改不要大改。5. 常见问题与排查技巧实录5.1 助手完全不读 skills 怎么办这是最常见的问题。排查顺序如下现象可能原因解决完全没反应没在项目说明里写加载指令补上“先读 INDEX.md”的说明偶尔读偶尔不读INDEX 太长或映射不清晰精简 INDEX每条映射写清场景读了但没用对skill 文件触发条件不明确在文件开头补“适用/不适用”说明读了但内容被忽略文件太长重点被稀释拆分文件单文件控制在 1500 字内我遇到最多的是第二种INDEX 写得太啰嗦助手判断场景时犹豫。精简之后命中率立刻上来。5.2 skills 之间内容冲突怎么办比如coding-style.md说函数不超过 50 行api-conventions.md里某个示例函数有 80 行。这种冲突会让助手无所适从。我的做法是建立优先级在 INDEX.md 里写明“具体示例优先于通用规范”或者干脆把冲突的示例改掉。规范体系最忌讳自相矛盾宁可少写一条也不要留下冲突。5.3 更新 skills 后助手还在用旧版这是缓存问题。Claude Code 和 Codex 都可能在一定时间内保留旧上下文。解决办法是在更新后开新会话或者在项目说明里加一句“skills 已更新请重新读取”。我一般直接开新会话最干净。5.4 多个项目共用一套 skills 怎么处理如果几个项目规范高度相似可以把 skills 抽到一个公共目录然后在各项目里用软链接或复制。我倾向于复制而不是软链接因为不同项目可能需要微调软链接改一处影响所有项目容易出意外。复制虽然笨但安全。提示公共 skills 更新后记得同步到各项目。我一般用一个简单的脚本做批量复制避免手动遗漏。5.5 怎么判断一个 skill 该不该拆判断标准很简单如果你在写这个文件时发现自己在写“另外”这个词超过两次就该拆了。比如“另外关于错误处理……另外关于日志……”这说明这个文件承载了多个主题。拆成独立文件INDEX 里各加一条映射即可。6. 进阶玩法让 skills 和 agents 配合起来6.1 skills 是知识agents 是执行者skills 解决的是“知道怎么做”agents 解决的是“实际去做”。两者配合的方式是agent 在执行任务前先根据任务类型加载对应 skill然后按 skill 里的步骤执行。我在一些自动化流程里就是这么做的一个负责代码审查的 agent启动时先读coding-style.md和api-conventions.md然后逐条对照检查。6.2 用 skills 约束 agent 的输出格式agent 最容易失控的地方是输出格式。今天用 JSON明天用 Markdown后天又变成纯文本。解决办法是在 skill 里强制规定输出格式并给出示例。比如审查报告的 skill# 审查报告格式 必须按以下结构输出 ## 问题列表 - [严重程度] 文件:行号 - 问题描述 ## 修改建议 - 文件:行号 - 具体改法 ## 总结 一句话说明整体质量。有了这个agent 的输出就稳定多了。6.3 把高频操作固化成 skill有些操作你每天都要做比如新建一个组件、加一个接口、写一个测试。这些都可以固化成 skill让 agent 照着做。我目前固化了大概七八个高频操作效率提升非常明显。关键是每次做完发现有问题就回头改 skill让它越来越准。6.4 注意 skills 的维护成本skills 不是写完就完事的它需要持续维护。我的经验是如果一套 skills 两周没更新基本就废了因为项目在变规范在变skills 不跟着变就会误导助手。所以我会在每周的固定时间花二十分钟过一遍该改的改该删的删。这个投入是值得的比每次重新解释省事得多。7. 我踩过的几个坑你可以直接避开第一个坑是一开始就追求大而全。我最早写了二十多个 skill 文件结果 INDEX 长得像目录助手根本读不完。后来砍到六个反而好用。所以别贪多先解决最痛的。第二个坑是把 skill 写成文档。文档是给人看的skill 是给模型看的。给人看的文档可以有大段背景介绍给模型看的 skill 必须直奔主题。我早期写的 skill 里有大量“背景说明”后来全删了只留可执行内容。第三个坑是忽略版本差异。Claude Code 和 Codex 的 skills 加载机制不完全一样我一开始用同一套配置套两个工具结果在 Codex 侧完全不生效。后来针对每个工具单独调才稳定下来。所以别指望一套配置通吃该分开就分开。第四个坑是不做验证。写完 skills 不测试等于没写。我现在每加一个 skill都会用一个典型任务验证它是否被正确加载和使用。这个习惯帮我省了很多返工。最后一个体会是skills 的价值不在于它有多完整而在于它有多准。一个只有三条但每条都精准命中的 skill 体系胜过一个有三十条但一半用不上的。所以别追求数量追求命中率。你可以在实际使用中慢慢加但每加一条都要问自己这条真的会被用到吗如果答案是“可能会”那就先别加。