1. 从"skills"这个模糊词说起：它到底指什么

第一次看到"skills"这个标题，很多人会一头雾水。它太宽泛了，宽泛到几乎等于没说。但结合热搜词里高频出现的 Claude Code、Codex、agents、plugin 这些词，方向其实很明确——这里说的 skills，指的是 AI 编程助手（尤其是 Claude Code 和 Codex 这类 agent 工具）里的技能扩展机制。

简单讲，skills 就是给 AI agent 装的一个个"技能包"。原生 agent 只会聊天、写代码、读文件，但装上 skills 之后，它能干的事情就多了：可以按你定义的流程去处理特定任务，可以调用外部工具，可以遵循一套固定的规范来输出结果。你可以把它理解成给一个刚入职的实习生发了一本《岗位操作手册》，手册里写清楚了遇到什么情况该怎么做。

为什么这个概念最近这么火？因为大家发现，光靠一个通用大模型，做出来的东西"能用但不好用"。你让它写个前端组件，它写出来的风格每次都不一样；你让它处理数据，它不知道你公司的字段规范。skills 解决的正是这个"最后一公里"的问题——把通用的能力，约束成符合你具体场景的专用能力。

这篇文章适合谁看？如果你是刚接触 Claude Code 或 Codex 的新手，想搞清楚 skills 是什么、怎么装、怎么用，那这篇能帮你少走弯路。如果你已经在用这些工具，但一直停留在"聊天式编程"的阶段，那这篇会告诉你 skills 能把效率拉到什么程度。我会从概念、安装、开发、踩坑几个角度，把这件事讲透。

2. Claude Code 与 Codex 的 skills 机制差异

2.1 Claude Code 的 skills 是怎么组织的

Claude Code 的 skills 本质上是一组放在特定目录下的文件，通常包含一个描述文件（说明这个 skill 叫什么、干什么、什么时候触发）和具体的执行逻辑。它的设计思路偏向"声明式"——你告诉它"遇到 X 场景就用 Y 流程"，它自己判断什么时候调用。

这种设计的好处是灵活。你不需要手动去触发，agent 会根据当前任务上下文自动匹配。比如你定义了一个"生成 React 组件"的 skill，当你让它写组件时，它会自动套用你预设的模板和规范。坏处是，如果描述写得不够精确，它可能该触发的时候不触发，或者不该触发的时候乱触发。

Claude Code 的 skills 目录结构一般长这样：

.claude/ skills/ my-skill/ SKILL.md # 技能描述与触发条件 scripts/ # 可选的辅助脚本 templates/ # 可选的模板文件

SKILL.md是整个技能的核心，里面用自然语言描述这个技能做什么、什么时候用、怎么用。这里有个关键点：描述要写得像给同事交代任务，而不是像写 API 文档。因为 agent 是靠语义理解来匹配的，你写得越接近真实使用场景，匹配越准。

2.2 Codex 的 skills 走的是另一条路

Codex 的 skills 更偏向"命令式"。它通常和 plugin 体系绑在一起，你需要显式地调用或者配置触发条件。Codex 生态里 skills 往往和具体的开发工具链结合得更紧，比如和 VS Code 插件、和特定的构建流程绑定。

这两种路线没有绝对优劣。Claude Code 的方式上手快、灵活，适合个人开发者快速试错；Codex 的方式更结构化，适合团队协作时统一规范。实际用下来，我个人的感受是：如果你追求"开箱即用、少配置"，Claude Code 的 skills 体验更顺；如果你需要把 skills 嵌进已有的工程化流程，Codex 的 plugin 机制更稳。

2.3 两者共同的底层逻辑

不管哪家，skills 的底层逻辑都是一样的：用结构化的描述，把隐性的经验显性化。你脑子里那些"我知道该这么做但说不清楚"的东西，通过 skills 变成 agent 能读懂的规则。

这里有个容易被忽略的点：skills 不是越多越好。我见过有人一口气装了二十几个 skills，结果 agent 每次决策都要在一堆规则里挑，反而变慢、变乱。真正有效的做法是围绕你最高频的 3 到 5 个场景来建 skills，把这几件事做到极致，比铺一堆半成品强得多。

3. 安装与配置：从零把 skills 跑起来

3.1 环境准备里最容易翻车的几个点

安装 Claude Code 或 Codex 本身不复杂，但 skills 相关的配置有几个坑，我一个个说。

第一个坑是目录位置。Claude Code 的 skills 默认读取项目根目录下的.claude/skills/，如果你放在用户主目录的全局配置里，行为会不一样。全局 skills 对所有项目生效，项目级 skills 只对当前项目生效。新手经常把项目级的 skill 放到全局目录，然后纳闷为什么换个项目就不生效了。

第二个坑是文件编码和换行符。SKILL.md这类文件如果编码不对（比如带了 BOM），agent 解析时可能读出一堆乱码。统一用 UTF-8 无 BOM，换行符用 LF，这是基本要求。

第三个坑是权限。如果你在 skill 里引用了脚本，脚本必须有可执行权限。在 Linux 或 macOS 下，chmod +x script.sh这一步别忘。Windows 下相对宽松，但如果你在 WSL 里跑，同样要注意。

3.2 一个最小可用的 skill 长什么样

别一上来就搞复杂的。先写一个最简单的，跑通了再迭代。下面是一个"生成规范提交信息"的 skill 示例：

--- name: commit-message description: 当用户要求生成 git commit message 时使用此技能 --- # 生成规范提交信息 ## 触发条件 用户提到"提交""commit""写提交信息"等关键词时。 ## 执行步骤 1. 查看当前暂存的改动（git diff --staged） 2. 按以下格式生成提交信息： - 类型(scope): 简短描述 - 类型可选：feat/fix/docs/style/refactor/test/chore 3. 描述用中文，不超过 50 字 4. 如果改动涉及多个不相关模块，建议拆分提交 ## 输出示例 feat(auth): 增加手机号登录校验

这个 skill 简单，但已经能解决一个真实痛点：团队里每个人提交信息格式不统一。写完之后，你让 agent 帮你提交，它就会自动按这个规范来。

3.3 验证 skill 是否生效的笨办法

装完 skill 之后，怎么确认它真的被加载了？最直接的办法是故意触发一次。比如上面那个 commit skill，你就正常让它帮你写提交信息，看输出格式对不对。

如果没生效，按这个顺序排查：

提示：改完 skill 文件后，最好重开一次会话。很多"改了没生效"的问题，都是因为 agent 还在用旧的内存缓存。

4. 开发自己的 skill：从需求到落地

4.1 先想清楚"这个 skill 解决什么重复劳动"

开发 skill 的第一步不是写代码，是找重复。你每天在 agent 面前重复说同样的话、重复纠正同样的错误，这些就是 skill 的候选。

我自己的做法是记一周的"抱怨日志"：每次我觉得"它怎么又这样"的时候，就记一笔。一周下来，出现频率最高的那几件事，就是最值得做成 skill 的。

常见的值得做成 skill 的场景：

• 代码风格统一（命名规范、注释格式、目录结构）
• 特定框架的脚手架生成（每次新建页面都要写一堆样板）
• 数据处理流程（固定的清洗、转换、校验步骤）
• 文档生成（按公司模板输出 README、API 文档）
• 代码审查清单（每次 review 都检查那几个点）

4.2 描述文件怎么写才"抓得准"

SKILL.md里的 description 字段是重中之重。它决定了 agent 什么时候会想起这个 skill。写得太窄，该用的时候不用；写得太宽，不该用的时候乱用。

我的经验是用"用户会说的话"来写描述，而不是用"技术术语"。比如：

• 差的写法：description: 用于处理 React 函数式组件的生成
• 好的写法：description: 当用户要求新建页面、新建组件、写一个 React 组件时使用

后者包含了用户真实会说的词——"新建页面""写个组件"，匹配率会高很多。

另外，description 里可以列几个反例，明确说什么情况下不要用。比如"不要用于修改已有组件，只用于新建"。这能有效减少误触发。

4.3 把流程拆成 agent 能执行的步骤

skill 正文部分，核心是把你的操作流程拆解成清晰的步骤。这里有个原则：每一步都要是 agent 能独立完成的动作。

什么叫"能独立完成"？比如"优化代码质量"就不是一个好步骤，太模糊了。改成"检查是否有未使用的 import 并删除""检查函数是否超过 50 行，超过则建议拆分"，这就可执行了。

我习惯用这样的结构来写正文：

## 执行步骤 1. [具体动作，带明确的判断标准] 2. [具体动作] 3. [输出格式要求] ## 注意事项 - [容易出错的地方] - [边界情况怎么处理] ## 输出示例 [给一个完整的例子]

给例子特别重要。agent 是模仿式学习，你给一个高质量的输出示例，它照着做的准确率会大幅提升。

4.4 迭代：第一版永远不够好

skill 写完不是终点。我的习惯是用一周，改三次。第一次改是修明显的 bug（触发不了、输出格式错），第二次改是补边界情况（遇到特殊情况怎么办），第三次改是精简（把啰嗦的描述砍掉，留下真正有用的）。

有个反直觉的发现：skill 写得越长，效果往往越差。因为 agent 的注意力有限，你塞太多规则进去，它反而抓不住重点。好的 skill 通常很短，核心规则就三五条，但每条都精准。

5. 实战中踩过的坑与排查链路

5.1 skill 死活不触发，我是怎么一步步定位的

这是最高频的问题。我遇到过一次，一个"生成单元测试"的 skill 怎么都不触发。排查过程如下：

第一步，确认文件在不在。ls .claude/skills/一看，文件在。

第二步，确认格式对不对。打开SKILL.md，发现 frontmatter 的结束---后面多了一个空行，然后才是正文。这个空行在某些版本里会导致解析失败。删掉，重试，还是不行。

第三步，看描述。原来的描述是"用于生成测试代码"。问题来了——用户实际说的是"帮我写个测试""给这个函数加测试"，没有"生成测试代码"这种说法。把描述改成"当用户要求写测试、加测试、生成单元测试时使用"，再试，触发了。

这个案例的教训是：排查要按"文件存在→格式正确→描述匹配"的顺序来，别一上来就怀疑玄学问题。大部分不触发都是描述词没对上。

5.2 多个 skill 打架怎么办

当你装了多个 skill，可能出现两个都想接管同一个任务的情况。比如你有一个"生成 React 组件"的 skill，又有一个"生成前端页面"的 skill，用户说"写个登录页"，两个都可能触发。

解决办法有两个。一是在描述里划清边界，明确"生成前端页面"只用于整页，"生成 React 组件"只用于局部组件。二是用优先级机制，如果工具支持的话，给更具体的 skill 更高优先级。

我个人的偏好是第一种，因为边界清晰对人对机器都好。写描述的时候多问自己一句："这个 skill 和相邻的 skill 区别在哪？"把这个区别写进描述里。

5.3 本地模型接入时的特殊问题

热搜词里有个"claude code 调用 lmstudio 的本地模型"，这涉及本地模型接入。用本地模型跑 skills 时，有个坑特别常见：本地模型的指令遵循能力通常弱于云端模型，你写的 skill 在云端跑得好好的，换本地模型就不听话了。

应对办法是把 skill 写得更"死"一点。云端模型能理解模糊指令，本地模型需要更明确的步骤。比如"优化一下"改成"删除未使用的变量，把超过 3 层的嵌套改成早返回"。步骤越具体，本地模型执行越稳。

另外，本地模型的上下文窗口往往更小，skill 正文别写太长，控制在 500 字以内比较安全。

5.4 那些"看起来是 bug 其实是设计"的情况

有些行为你以为是故障，其实是正常设计。比如 skill 触发后 agent 没有完全按步骤走，跳过了某一步。这通常是因为 agent 判断那一步在当前上下文里不适用。如果你确实要求它每步都走，就在 skill 里明确写"必须逐步执行，不得跳过"。

还有一种情况：skill 在 A 项目生效，在 B 项目不生效。先别急着骂工具，检查一下 B 项目是不是没有.claude/skills/目录，或者 B 项目用的是全局配置而 skill 放在了项目级目录。

6. 让 skills 真正提升效率的几个心得

6.1 从"记录"开始，而不是从"设计"开始

很多人一上来就想设计一套完美的 skill 体系，结果卡在设计阶段。我的建议是反过来：先记录，后设计。用最笨的办法，把每次重复的操作记下来，记够十条再回头看，哪些能合并、哪些能抽象，自然就清楚了。

这就像整理房间，你得先把东西都摊出来，才知道该怎么归类。凭空设计分类体系，往往不贴合实际。

6.2 skill 的粒度：宁可小，不要大

一个 skill 只干一件事。我见过有人写一个"全能开发助手" skill，里面塞了生成代码、写测试、写文档、提交代码所有流程。结果就是每个环节都做得马马虎虎。

拆成四个独立 skill 之后，每个都能打磨得很精细。而且独立 skill 可以自由组合，灵活性反而更高。粒度小还有个好处：出问题好定位。一个 skill 出问题，影响范围就那么大，不会牵一发动全身。

6.3 定期清理，别让 skill 库变成垃圾场

skill 会过时。半年前写的 skill，可能因为项目重构、规范变更已经不再适用。我建议每个月花十分钟过一遍 skill 列表，把不再用的删掉，把需要更新的改一改。

留着过时的 skill 比没有更糟，因为它会在不该触发的时候触发，给你添乱。清理的标准很简单：过去一个月没用过的，要么删，要么想想为什么没用——是场景变了，还是描述写得太差导致触发不了。

6.4 团队协作时怎么共享 skills

如果是团队用，skills 应该跟着代码仓库走，放在项目里的.claude/skills/目录，提交到版本控制。这样每个人拉下代码就自动有了统一的 skills。

但要注意敏感信息。skill 里别写死密钥、内部地址这类东西，用环境变量或者占位符代替。我见过有人把数据库连接串写进 skill 的示例里，然后提交到了公开仓库，这就很危险。

另外，团队共享的 skill 要有维护人。谁改的、为什么改，最好在提交信息里写清楚。不然过几个月没人知道某个 skill 为什么长这样，想改都不敢改。

6.5 一个我常用的调试技巧

当 skill 行为不符合预期时，我会在 skill 里临时加一句"在执行前，先输出你打算怎么做"。这样 agent 会把它理解的执行计划打印出来，我一眼就能看出是它理解错了，还是我描述写错了。

定位完问题，再把这句话删掉。这个技巧特别适合排查"它为什么这么做"这类问题，比反复读 skill 文件有效得多。

7. 关于 skills 生态的一些观察

skills 这个方向，目前还处在早期。Claude Code 和 Codex 各自的机制不一样，社区里也没有统一的标准。这意味着两件事：一是现在投入学习，能吃到早期红利；二是别把宝全押在一家上，保持对另一家的关注。

我个人的判断是，未来 skills 会往两个方向走。一个是标准化，可能会出现跨工具通用的 skill 格式，写一次到处能用。另一个是市场化，会出现 skill 的分享和交易平台，好用的 skill 能直接拿来用，不用自己从头写。

对普通开发者来说，现在最实际的做法是：先在自己最高频的场景上把 skill 用起来，积累经验。等生态成熟了，你已经有了一套自己的方法论，迁移成本会低很多。

热搜里还有个词叫"agent skills 测试"，说明已经有人在做 skill 的质量评估了。这是个好信号，说明这个领域在往工程化方向走。等测试标准出来了，写 skill 会从"手艺"变成"工程"，那时候门槛会更低，但竞争也会更激烈。现在多练手，没坏处。

最后分享一个我自己的习惯：每写一个新 skill，我都会在文件顶部留一行注释，写上创建日期和一句话说明为什么建它。过几个月回头看，这行注释能帮我快速判断这个 skill 还有没有存在的必要。小习惯，但省了不少纠结的时间。