1. 从“skills”这个模糊词说起：它到底指什么
第一次看到“skills”这个词单独作为项目标题，说实话我是有点懵的。它太宽泛了，宽泛到几乎可以套在任何东西上。但结合热搜词里反复出现的 Claude Code、Codex、plugin、agents 这些词，方向就清晰了——这里说的 skills，不是泛泛而谈的“技能”，而是围绕 AI 编程助手（尤其是 Claude Code 和 Codex 这类命令行 Agent 工具）构建的可复用能力单元。
你可以把它理解成给 AI 助手装的“插件包”或者“技能卡”。一个 skill 通常包含一段结构化的指令、若干工具调用约定、以及特定场景下的行为规范。当你在 Claude Code 里输入某个触发词，或者当 Agent 判断当前任务匹配某个 skill 的描述时，它就会加载这套预设，按照里面定义的流程去干活。这跟传统 IDE 插件最大的区别在于：传统插件是给人用的，skill 是给 Agent 用的。人点按钮，Agent 读描述。
为什么这个概念突然火起来了？因为大家发现，光有一个聪明的模型不够。模型再强，每次都要从零开始解释“帮我写个 React 组件，用 TypeScript，样式用 Tailwind，测试用 Vitest”，效率太低。skills 解决的就是这个“每次都要重新教”的问题。你把一套标准流程固化成一个 skill，下次 Agent 自己就知道该怎么做。这跟当年从手写 SQL 到 ORM 的演进逻辑是一样的——把重复劳动抽象掉。
热搜词里还有“claude agent skills: a first principles deep dive”这样的条目，说明已经有人在从第一性原理层面拆解这个机制了。我的判断是，skills 本质上是一种面向 Agent 的提示工程封装格式。它把 prompt、工具定义、上下文管理策略打包在一起，形成一个可分发、可版本控制的单元。你可以在团队内共享，也可以从社区获取别人写好的 skill 直接安装。
适合谁来了解这个内容？三类人：一是已经在用 Claude Code 或 Codex 做日常开发的工程师，想提升效率；二是对 Agent 架构感兴趣、想自己写 skill 的技术人；三是团队技术负责人，在考虑要不要把 skills 纳入团队的标准化工具链。不管你是哪类，下面这些内容应该都能帮你少走弯路。
2. Claude Code 与 Codex 的 skills 机制差异
2.1 Claude Code 的 skill 加载逻辑
Claude Code 对 skills 的处理方式比较“重”。它有一套明确的 skill 发现和加载机制。当你在项目根目录或者用户配置目录下放置 skill 文件时，Claude Code 会在启动时扫描这些位置，把 skill 的元信息（名称、描述、触发条件）读入上下文。注意，这里读入的只是元信息，不是完整内容。只有当 Agent 判断当前任务需要用到某个 skill 时，才会把完整内容加载进来。
这个设计很聪明。因为上下文窗口是稀缺资源，如果把所有 skill 的完整内容都塞进去，还没开始干活上下文就满了。所以 Claude Code 采用的是惰性加载策略。元信息里最关键的是 description 字段，Agent 就是靠这个字段来判断“这个 skill 跟当前任务有没有关系”。所以写 skill 的时候，description 一定要写得精准，既不能太窄导致该触发的时候不触发，也不能太宽导致频繁误触发。
我实测下来的经验是，description 里最好包含具体的触发场景关键词。比如你写一个“生成 API 文档”的 skill，description 里就应该出现“API 文档”“接口说明”“endpoint 描述”这类词。Agent 在匹配时做的是语义相似度判断，关键词密度会影响匹配权重。
2.2 Codex 的 skill 集成方式
Codex 这边的思路略有不同。Codex 本身是 OpenAI 出的命令行编程助手，它对 skills 的支持更多体现在配置驱动上。你通过配置文件定义一组行为规则和工具权限，Codex 在执行任务时会参考这些配置。热搜词里出现的“codex is ignoring 1 unrecognized configuration setting”这类报错，往往就是因为配置文件的字段名写错了，或者用了当前版本不支持的字段。
Codex 的 skill 更偏向于“能力声明”而非“流程封装”。你告诉它“你可以访问数据库”“你可以调用某个 API”，然后它在需要的时候自己去组合这些能力。这跟 Claude Code 那种“我教你一套完整流程”的风格形成对比。两种方式各有优劣：Claude Code 的 skill 更可控，适合标准化流程；Codex 的方式更灵活，适合探索性任务。
有个细节值得注意：热搜词里出现了“codex接入deepseek”和“claude code 调用lmstudio的本地模型”。这说明很多人不满足于官方模型，想把 skills 机制跟本地模型或者第三方模型结合起来。这个方向是可行的，但要注意模型能力差异。同一个 skill，在强模型上跑得好，换到弱模型上可能就各种出错。因为 skill 里的指令往往隐含了对模型理解能力的假设。
2.3 两者在 plugin 生态上的分野
Claude Code 有官方的 plugin 市场概念，热搜词里“claude 国内安装skills 官方市场”说明国内用户也在关注怎么从官方渠道获取 skill。而 Codex 这边更多是社区自发分享，没有统一的 marketplace。这个差异导致了一个现象：Claude Code 的 skill 质量相对有保障，因为有官方审核；Codex 的 skill 则良莠不齐，需要自己甄别。
从技术架构上看，Claude Code 的 plugin 机制支持更复杂的依赖关系。一个 skill 可以依赖另一个 skill，形成技能树。Codex 目前还比较简单，基本是扁平的配置项。如果你要做复杂的多步骤工作流，Claude Code 的 skill 体系会更适合。
3. 一个 skill 文件里到底该写什么
3.1 元信息部分：名称与描述的写法
写 skill 的第一步是定义元信息。名称要短、要唯一、要能望文生义。别起那种“my-awesome-skill-v2-final”的名字，Agent 看了也不知道是干嘛的。好的名称像“react-component-gen”“api-doc-writer”“db-migration-helper”，一看就知道用途。
描述部分是最容易写砸的地方。我见过太多人把描述写成了一段功能列表，什么“这个 skill 可以帮你生成代码、检查语法、运行测试、提交 git”。这种描述对 Agent 来说信息量太低，因为几乎所有编程 skill 都能干这些。好的描述应该聚焦在差异化特征上。比如“当用户需要为现有 React 项目添加新的函数组件，且项目使用 TypeScript 和 Tailwind CSS 时使用此 skill”。这样 Agent 就能精确判断什么时候该加载。
还有一个坑：描述里不要用否定句。你写“不要用于 Vue 项目”，Agent 对否定信息的处理能力很弱，很可能反而把 Vue 项目也匹配上。正确的做法是只描述正面场景，让不匹配的场景自然落空。
3.2 指令主体：流程与约束的平衡
指令主体是 skill 的核心。这里要解决一个矛盾：写得太细，Agent 没有发挥空间，遇到稍微不同的情况就卡住；写得太粗，Agent 自由发挥，结果不可控。我的经验是关键步骤写死，边缘情况给原则。
举个例子，一个“生成数据库迁移脚本”的 skill。关键步骤可以写死：先检查当前 schema 版本，再对比目标版本，生成 diff，最后输出迁移文件。这些步骤的顺序不能乱。但具体用什么工具做 diff、迁移文件命名格式怎么定，可以给一个默认值加一句“如果项目已有约定则遵循项目约定”。这样既保证了流程正确，又保留了灵活性。
约束条件要明确写出来。比如“生成的代码必须通过 ESLint 检查”“不允许修改现有测试文件”“所有新增依赖必须记录在 package.json 中”。这些硬性约束是保证 skill 输出质量的关键。没有约束的 skill 就像没有刹车的车，跑得越快越危险。
3.3 工具权限声明：最小必要原则
Skill 里通常需要声明它能使用哪些工具。Claude Code 这边叫 tool use，Codex 那边叫 function calling。不管叫什么，原则是一样的：只声明必要的工具，不要贪多。
我见过一个 skill 声明了文件读写、网络请求、shell 执行、数据库连接等一大堆权限，结果只是用来生成一个 Markdown 文档。这种过度授权有两个问题：一是安全风险，万一 skill 被恶意利用，破坏力很大；二是干扰 Agent 判断，工具太多反而让 Agent 不知道该用哪个。
正确的做法是列一个最小工具集。生成文档的 skill 只需要文件写入权限，最多加一个读取现有文档的权限。需要跑测试的 skill 才加 shell 执行权限，而且要限定只能执行测试命令。Claude Code 支持在 skill 里对工具调用做更细粒度的约束，比如限制 shell 命令的白名单。这个特性要用起来。
4. 从零写一个可用的 skill：完整实操
4.1 场景选择：为什么从“代码审查”入手
我建议第一个 skill 从代码审查开始写。原因有三：第一，代码审查的流程相对标准化，容易定义；第二，审查结果的好坏容易验证，你能快速判断 skill 有没有效果；第三，这个场景对工具权限的要求适中，不会一上来就涉及危险操作。
假设我们要写一个“PR 代码审查”skill。它的目标是：当用户请求审查一个 Pull Request 时，Agent 自动拉取 diff、逐文件分析、检查常见问题、输出结构化审查意见。
4.2 文件结构与放置位置
Claude Code 的 skill 通常放在项目根目录的.claude/skills/下，每个 skill 一个文件夹，里面至少有一个SKILL.md文件。Codex 的配置则通常在~/.codex/或项目级的.codex/目录下。具体路径取决于你的工具版本，建议先查一下官方文档确认。
一个典型的 skill 文件夹结构是这样的：
.claude/skills/pr-review/ ├── SKILL.md # 主文件，包含元信息和指令 ├── templates/ │ └── review-template.md # 审查意见的输出模板 └── examples/ └── sample-review.md # 示例输出，供 Agent 参考SKILL.md的头部用 YAML frontmatter 写元信息，下面用 Markdown 写指令。这个格式跟很多静态站点生成器类似，上手不难。
4.3 指令编写：把审查流程拆成可执行步骤
指令部分我一般分成四块写：触发条件、前置检查、执行步骤、输出格式。
触发条件这块要写清楚什么情况下用这个 skill。比如“当用户消息中包含‘审查 PR’‘review pull request’‘检查代码变更’等意图时触发”。
前置检查是很多人会忽略的。Agent 在执行前应该先确认一些前提条件，比如“当前目录是一个 git 仓库”“存在至少一个远程分支”“gh 命令行工具已安装并认证”。如果前置条件不满足，Agent 应该给出明确提示而不是硬着头皮往下做。
执行步骤要拆得足够细。我通常写成有序列表，每一步都是一个明确的动作。比如：
- 运行
gh pr diff获取变更内容 - 按文件分组，识别每个文件的变更类型（新增/修改/删除）
- 对每个修改的文件，检查以下维度：命名规范、错误处理、边界条件、测试覆盖
- 汇总发现的问题，按严重程度分级
- 按照模板输出审查报告
输出格式部分，我会在 skill 里直接嵌入模板的引用，让 Agent 知道最终产出应该长什么样。模板文件放在templates/目录下，Agent 会去读取。
4.4 测试与迭代：怎么判断 skill 写得好不好
写完 skill 只是开始，测试才是关键。我的测试方法是：准备三个不同类型的 PR——一个简单的小改动、一个涉及多文件的重构、一个包含明显 bug 的提交。然后分别让 Agent 用这个 skill 去审查，看输出是否符合预期。
判断标准有三条：第一，Agent 有没有正确触发这个 skill；第二，执行步骤有没有遗漏或顺序错乱；第三，输出格式是否稳定。如果三条都满足，这个 skill 基本可用。如果某一条不满足，就针对性地改指令。
迭代的时候要注意，每次只改一个地方。同时改多个地方，出了问题你都不知道是哪个改动导致的。我一般会在 skill 文件里留一个版本号注释，每次修改都记一笔改了什么、为什么改。
5. 那些让我踩过坑的细节
5.1 描述写得太宽导致的误触发
我最早写的一个 skill 是“代码优化助手”，描述写的是“帮助优化代码质量”。结果这个 skill 几乎在所有编程任务里都会被触发，包括那些根本不需要优化的场景。Agent 每次都要加载它，浪费上下文不说，还经常在不该优化的时候强行给优化建议，干扰正常流程。
后来我把描述改成了“当用户明确要求对现有函数进行性能优化，且该函数已有性能测试覆盖时使用”。触发频率立刻降下来了，而且每次触发都是真正需要的场景。这个教训是：描述里的限定条件越多，触发越精准。宁可少触发，也不要乱触发。
5.2 指令里的隐含假设
有一次我写了一个“生成单元测试”的 skill，指令里写“为每个导出函数生成测试用例”。听起来没问题，但实际跑的时候发现，有些函数是纯类型定义或者常量导出，根本不需要测试。Agent 却老老实实地给每个导出都生成了测试，包括那些空函数。
问题出在“每个导出函数”这个表述上。它隐含了一个假设：所有导出都是需要测试的函数。但实际上不是。后来我改成“为每个包含可执行逻辑的导出函数生成测试用例，跳过纯类型定义、常量和空函数”。这样 Agent 就有了判断依据。
写 skill 指令的时候，要时刻问自己：这句话有没有隐含假设？如果有，就要把假设显式写出来。Agent 不会像人一样“意会”，它只会按字面执行。
5.3 工具权限过大引发的连锁反应
前面提过最小权限原则，这里说一个具体的坑。我曾经给一个“自动修复 lint 错误”的 skill 授予了完整的 shell 执行权限，想着这样它就能跑各种 lint 工具了。结果有一次，Agent 在修复一个格式问题时，自作主张地运行了git commit，把一堆未完成的改动一起提交了。
这个问题的根源就是权限过大。后来我把 shell 权限限制为只能执行eslint和prettier这两个命令，其他命令一律拒绝。Agent 就再也没法做多余的操作了。Claude Code 支持在 skill 配置里写命令白名单，这个功能一定要用。
5.4 版本兼容性问题
热搜词里有一条“codex is ignoring 1 unrecognized configuration setting. check for typos or d”，这说的就是配置字段不被识别的问题。Skills 的格式规范还在快速演进中，不同版本的工具支持的字段可能不一样。你照着网上教程写的 skill，在自己的工具版本上可能就跑不起来。
我的应对策略是：第一，写 skill 前先确认工具版本，查对应版本的文档；第二，skill 文件里尽量只用核心字段，少用实验性特性；第三，如果必须用新特性，在 skill 描述里注明最低版本要求。这样别人用的时候至少知道为什么跑不起来。
6. 社区里那些值得关注的 skills 方向
6.1 文档生成类 skill 的实际效果
文档生成是目前社区里最成熟的 skill 类别之一。我试过几个开源的 API 文档生成 skill，整体效果不错，但有一个共性问题：生成的文档偏向“翻译代码”，而不是“解释意图”。比如一个函数叫calculateDiscount，文档生成 skill 会写“计算折扣”，但不会解释折扣的计算规则是什么、边界条件有哪些。
要解决这个问题，skill 里需要引导 Agent 去读测试用例和注释，从里面提取业务规则。我在自己的 skill 里加了一步“读取该函数相关的测试文件，从测试用例中提取业务规则描述”，效果明显改善。这个思路可以推广到其他生成类 skill：让 Agent 从测试和注释里找意图，而不是从代码字面猜意图。
6.2 测试相关 skill 的边界
测试生成 skill 的边界比想象中难把握。生成一个能跑的测试很容易，生成一个有价值的测试很难。有价值的测试要覆盖边界条件、异常路径、并发场景，这些光看函数签名是看不出来的。
我目前的做法是，在 skill 里要求 Agent 先分析函数的输入域，识别出等价类和边界值，然后针对每个等价类生成至少一个测试用例。同时要求它检查现有的测试文件，避免重复生成已经覆盖的场景。这套流程跑下来，生成的测试质量比“每个函数生成一个 happy path 测试”要好得多。
6.3 重构类 skill 的风险控制
重构类 skill 是风险最高的。因为重构会改动现有代码，一旦出错可能引入 bug。我见过一个自动重构 skill，把一个大函数拆成多个小函数，结果拆出来的函数之间有隐藏的状态依赖，导致行为改变。
控制这类风险的关键是：重构 skill 必须包含验证步骤。我的做法是在 skill 里强制要求：重构后必须运行现有测试套件，如果测试失败则回滚改动并报告问题。同时要求 Agent 在重构前先记录当前测试通过率，重构后再对比。这样即使出了问题，也能及时发现。
热搜词里“agent skills测试”和“skills开发”这两个词放在一起，说明大家已经意识到 skill 本身也需要测试。我完全同意。一个没有经过测试的 skill，就像一段没有测试的代码，你不知道它什么时候会崩。
7. 把 skills 纳入日常工作流的实际体会
我现在的工作流是这样的：项目根目录下维护一个.claude/skills/文件夹，里面放团队共用的 skill。每个人本地还可以有.claude/skills.local/放个人 skill。团队 skill 通过 git 管理，改动走 PR 流程。这样既能共享，又能保证质量。
实际用下来，最大的收益不是“省了多少时间”，而是“减少了多少沟通成本”。以前新人入职，要花好几天熟悉项目的代码规范和审查流程。现在把这些都写成 skill，新人装好工具就能按标准流程干活。当然，skill 不能替代文档，它更像是把文档里的流程变成了可执行的指令。
有一个坑要提醒：不要试图用 skill 解决所有问题。有些任务就是需要人的判断，硬写成 skill 反而会限制 Agent 的发挥。我的经验法则是：如果一个任务的流程能在三次以内说清楚，就适合写成 skill；如果需要大量“视情况而定”，那就不适合。
最后分享一个我最近在用的技巧：给 skill 加一个“自检”步骤。在 skill 指令的最后，要求 Agent 在输出结果前先自己检查一遍，确认所有约束都满足了、所有步骤都执行了。这个简单的自检步骤，能减少相当一部分低级错误。实测下来，加了自检的 skill，输出合格率明显高于没加的。这个技巧不复杂，但很管用。
