1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题我脑子里蹦出来的其实是三个完全不同的东西一是 Claude Code 里的 Agent Skills 机制二是 Codex 的 skills 扩展能力三是泛指的技能包概念。这三个东西名字撞车但底层逻辑差得挺远。热词里同时出现了claude agent skills: a first principles deep dive、codex skills、agent skills测试、skills开发说明大家真正关心的不是skills 是什么这种定义题而是我怎么把 skills 用起来、写出来、调通。先把范围收一下。这篇聊的 skills指的是围绕 AI 编程助手Claude Code、Codex 这类 agent 工具构建的可复用能力单元。它不是一个新语言也不是一个 SDK本质上是把一段固定的工作流、领域知识或者操作规范打包成 agent 能自动识别并调用的模块。你可以把它理解成给 agent 装的插件说明书——agent 本身会写代码但它不知道你们团队的代码规范、不知道你们内部 API 的调用姿势、不知道某个业务字段的坑skills 就是把这些隐性知识显性化。为什么这个东西突然火因为大家用 Claude Code、Codex 写代码写到一定阶段都会撞到同一堵墙通用能力很强但一到具体项目就水土不服。你让它改个 React 组件它给你写个 class component你让它调内部接口它编一个不存在的字段名。每次都要在 prompt 里重复交代背景效率极低。skills 要解决的就是这个重复交代的问题——一次写好长期复用。适合谁看三类人一是已经在用 Claude Code / Codex 但还没碰过 skills 的开发者二是想给团队沉淀规范、让 AI 输出更稳定的技术负责人三是好奇 agent 扩展机制、想自己写 skill 的折腾党。如果你连 Claude Code 都还没装建议先看安装部分再回来看 skills 的设计思路。提示skills 这个概念在不同工具里叫法不同Claude Code 叫 Agent SkillsCodex 生态里也有类似的 skills 目录约定。本文以通用机制为主具体路径以你所用工具的官方文档为准。2. Claude Code 与 Codex 里 skills 的定位差异2.1 Claude Code 的 Agent Skills基于文件系统的能力注入Claude Code 的 skills 机制核心思路是基于文件系统的约定式加载。你在特定目录下放一个 skill 定义文件通常包含元信息和正文指令Claude Code 在启动或执行任务时会扫描这些目录把匹配的 skill 内容注入到上下文里。它不需要你写代码注册也不需要编译改完文件重启会话就生效。这个设计的好处是零构建成本。你不需要懂任何插件 API只要会写 Markdown 就能写 skill。坏处是加载时机和优先级需要你自己控制——skill 太多会挤占上下文窗口写得太泛会跟系统提示词打架。我实测下来单个 skill 正文控制在 500 到 1500 字比较舒服超过 2000 字就开始明显吃 token而且 agent 对超长 skill 的遵循度会下降。Claude Code 的 skill 通常包含几个关键部分name唯一标识、description什么时候该用这个 skill这段最关键、以及正文指令。description写得好不好直接决定 agent 能不能在正确的时机触发它。很多人 skill 写了但从不触发九成是 description 写得太抽象比如写帮助处理代码agent 根本不知道啥时候该用。2.2 Codex 生态的 skills更偏向工程化集成Codex 这边的 skills 思路略有不同它更强调与工程流程的集成。热词里codex skills、codex接入deepseek、codex无法加载组织设置这些词放在一起看能看出 Codex 用户更关心的是skill 能不能跟我的模型、我的组织配置、我的 CI 流程打通。Codex 的 skill 往往需要配合配置文件、环境变量、甚至组织级别的策略来用。这就带来一个典型问题本地能跑换台机器或者换个组织就挂。codex无法加载组织设置这个热词背后大概率就是 skill 依赖了某些组织级配置但新环境没同步。我的经验是写 Codex skill 时尽量把依赖显式声明出来别隐式依赖全局配置否则迁移时必踩坑。2.3 两者的共同底层逻辑抛开工具差异skills 的底层逻辑是一致的用自然语言或半结构化文本描述在什么场景下做什么事让 agent 在运行时按需加载。它跟传统的函数调用、插件 API 最大的区别是——没有严格的接口契约。你写的是建议agent 可以选择遵循也可以选择忽略。这既是灵活性来源也是不稳定的根源。理解这一点很重要skills 不是确定性代码是概率性引导。你没法保证 agent 100% 按 skill 执行只能通过写得更具体、给更多示例、加更明确的触发条件来提高遵循率。想追求确定性那得用 tool calling 或者写真正的插件不是 skills 的范畴。维度Claude Code Agent SkillsCodex 生态 skills加载方式文件系统扫描约定目录配置驱动可能涉及组织策略编写门槛会写 Markdown 即可需要理解配置与环境依赖生效时机会话启动或任务匹配时注入依赖配置加载与模型路由主要坑点上下文挤占、触发不准环境迁移、组织设置不同步适合场景个人/小团队快速沉淀工程化、多环境统一管理3. 一个 skill 从零到能用的完整搭建过程3.1 先想清楚这个 skill 解决什么重复问题我见过太多人上来就写 skill写完发现根本用不上。正确的顺序是先记录痛点再抽象成 skill。具体做法接下来一周每次你在 prompt 里重复交代同一类背景超过三次就记下来。比如我们项目用 pnpm 不用 npm接口返回统一包了一层 data 字段组件必须用函数式写法。这些重复出现的约束就是 skill 的候选内容。判断一个痛点值不值得做成 skill我用三个标准高频一周至少触发几次、稳定规则不常变、可描述能用文字讲清楚。三个都满足才做。低频的、易变的、说不清的老老实实每次手写 prompt 更划算。3.2 skill 文件的结构与字段写法一个典型的 skill 定义结构上分两块元信息头和指令正文。元信息头负责让 agent 知道这个 skill 存在以及何时用指令正文负责告诉 agent 具体怎么做。元信息里最关键的是description。我总结了一个写法模板当用户需要 [具体动作] 且涉及 [具体对象] 时使用本 skill它会 [具体产出]。举个例子别写处理数据库相关任务要写当用户需要编写或修改 PostgreSQL 查询且涉及分页时使用本 skill它会按项目约定的 keyset 分页写法生成 SQL 并附带索引建议。后者 agent 一看就知道啥时候该调。指令正文我建议按这个顺序组织背景约束 → 操作步骤 → 正例 → 反例 → 边界情况。正例反例特别重要agent 对对比的敏感度远高于纯描述。你给它一个这样写对、那样写错的对照遵循率能明显提升。--- name: pg-keyset-pagination description: 当用户需要编写或修改 PostgreSQL 分页查询时使用本 skill它会按 keyset 分页写法生成 SQL 并附带索引建议。 --- ## 背景约束 - 项目统一使用 keyset 分页禁止 OFFSET 分页 - 排序字段必须建索引 - 返回结果统一包一层 { data, nextCursor } ## 操作步骤 1. 确认排序字段和唯一键 2. 生成 WHERE (sort_col, id) (last_sort, last_id) 形式 3. 补 LIMIT 4. 检查索引是否覆盖排序字段 ## 正例 ...贴一段正确 SQL ## 反例 ...贴一段 OFFSET 写法并说明为什么错3.3 放置位置与加载验证文件写好后放到工具约定的 skills 目录。Claude Code 一般是项目根目录或用户目录下的特定文件夹Codex 则可能需要在配置里显式声明路径。放好之后一定要验证是否真的被加载——最直接的办法是开一个新会话问 agent你现在有哪些可用的 skill看它列出来的清单里有没有你刚写的那个。如果没加载排查顺序是路径对不对 → 文件名和元信息格式对不对 → 有没有语法错误导致解析失败 → 是否需要重启会话。我踩过最蠢的坑是 YAML 头里的冒号后面没加空格整个 skill 静默失效查了半小时。注意改完 skill 文件后正在进行的会话通常不会热加载必须新开会话才生效。别在旧会话里反复测试然后怀疑自己写错了。4. 让 skill 真正被触发的几个关键技巧4.1 description 的触发词设计skill 不触发90% 是 description 的问题。agent 判断要不要用这个 skill靠的是把你的当前任务和 skill 的 description 做语义匹配。所以 description 里要包含用户实际会说的词而不是你抽象出来的术语。比如你写处理认证逻辑用户实际说的是登录token 过期鉴权失败。那 description 里就该把这些词都覆盖进去。我的做法是写完 description 后自己模拟五种不同的提问方式看能不能都匹配上。匹配不上的就把对应关键词补进去。还有一个技巧是在 description 里写清楚不适用场景。有些 skill 之间会互相抢触发比如React 组件编写和React 性能优化两个 skill如果不写清楚边界agent 可能在该优化的时候去调编写 skill。加一句本 skill 不处理性能优化那属于 xxx skill能有效减少误触发。4.2 控制 skill 数量和上下文占用skill 不是越多越好。每个被加载的 skill 都占上下文加载太多会导致两个后果一是真正重要的指令被稀释agent 注意力分散二是 token 成本飙升长会话里尤其明显。我的经验值是单个项目常驻 skill 控制在 5 到 8 个每个正文 500 到 1500 字。超过这个量就要考虑合并或者改成按需加载。有些工具支持只在匹配时才加载正文这种机制下可以多放一些但 description 的总量还是要控制。合并的原则是同领域合并、跨领域拆分。比如代码风格命名规范注释要求可以合成一个编码规范skill但数据库操作和前端组件就别硬塞一起触发场景差太远。4.3 用测试用例反向验证 skill 质量写完 skill 别急着用先做一轮触发测试。准备 10 个测试问题5 个应该触发这个 skill 的5 个不应该触发的。然后新开会话逐个问记录 agent 有没有正确调用。应该触发却没触发的说明 description 覆盖不够不该触发却触发了的说明边界没写清。这个测试做一轮skill 质量能提升一大截。我一般会把测试用例存成一个文件每次改完 skill 重跑一遍防止改 A 坏 B。热词里有个agent skills测试说明已经有人在做系统化的 skill 测试了。这事确实值得投入因为 skill 的隐性 bug该触发不触发比显性 bug 更难发现不测试根本不知道。5. 安装与环境配置里那些容易翻车的地方5.1 Claude Code 安装与 skills 目录初始化Claude Code 的安装本身不复杂但热词里claude code安装、claude code windows、ubuntu配置claude code、vscode配置claude code同时出现说明跨平台配置是重灾区。Windows 上主要是路径和权限问题Linux 上主要是 Node 版本和全局安装权限VS Code 里则是插件和 CLI 的版本要对齐。装完之后skills 目录不会自动创建得手动建。我建议项目级 skill 放项目里个人通用 skill 放用户目录这样项目 skill 能跟着代码走团队共享个人 skill 跨项目复用。别把所有 skill 都堆在用户目录否则换个项目一堆无关 skill 在抢触发。5.2 Codex 安装与模型接入的坑codex安装、codex安装教程、codex安装 csdn、codex官网下载、codex登录这一串热词基本勾勒出新手装 Codex 的完整踩坑路径。安装本身按官方文档走就行真正容易出问题的是模型接入。codex接入deepseek这个热词说明很多人想用非默认模型这时候 skill 的行为可能会变——不同模型对同一段 skill 指令的遵循度不一样。我的建议是换模型后一定要重跑 skill 触发测试。同一个 skill在 A 模型上触发得好好的换 B 模型可能就失灵了。这不是 skill 写错了是模型对 description 的语义理解有差异。遇到这种情况微调 description 的措辞往往比重写整个 skill 有效。5.3 环境迁移时的 skill 同步问题codex无法加载组织设置这个热词点出了一个高频问题skill 依赖的环境配置没跟着迁移。skill 文件本身好复制但它依赖的环境变量、组织策略、模型路由配置往往散落在各处迁移时容易漏。我的做法是给每个 skill 配一个deps.md显式列出它依赖的环境变量、配置项、外部工具。迁移时照着清单一项项核对。虽然麻烦但比跑起来发现不对再回头查省时间得多。常见报错/现象可能原因排查方向skill 完全不触发description 语义不匹配补充用户实际用词加触发测试触发但行为不对正文指令有歧义加正反例明确边界换机器后失效环境依赖未同步检查 deps 清单核对配置会话变慢/变贵skill 加载过多精简数量合并同领域 skill换模型后失灵模型语义理解差异微调 description 措辞6. 从能用到好用skill 的迭代与团队协作6.1 建立 skill 的版本与变更记录skill 是活的项目规范变了、工具升级了、踩了新坑skill 都得跟着改。问题是改完之后怎么知道改了啥、为什么改我强烈建议每个 skill 文件顶部维护一个变更记录简单几行就行日期、改了什么、为什么改。这么做的好处是当 skill 行为突然变化时你能快速定位是不是最近某次修改引入的。我遇到过 skill 改了一句话导致触发率暴跌的情况因为有变更记录五分钟就定位到了。没有记录的话可能得把整个 skill 重读一遍找差异。6.2 团队共享 skill 的目录组织团队用 skill目录组织很关键。我的建议是按领域分层skills/下按frontend/、backend/、database/、workflow/分目录每个目录里放对应 skill。这样新人一眼能看懂有哪些能力可用也方便按需加载。共享方式上跟代码一起进版本库是最省事的。skill 文件本身就是文本diff 友好review 也方便。别搞什么独立的 skill 管理平台除非规模真的很大否则维护成本超过收益。6.3 什么时候该把 skill 升级成真正的插件skill 有天花板。当你的需求从引导 agent 怎么做变成必须保证 agent 这么做时就该考虑升级成插件或 tool 了。判断标准很简单如果 skill 没被遵循会导致严重后果数据错误、安全事故那就不能用 skill得用确定性代码。skill 适合的是建议性、引导性的场景比如代码风格、命名习惯、文档格式。涉及数据写入、权限校验、资金操作这类老老实实写插件或者在后端做校验别指望 skill 兜底。热词里skills开发、idea使用skills、idea设置plugin中插件仓库地址这些词放在一起其实反映了大家正在从用现成 skill往自己开发 skill 和插件过渡。这个过渡是自然的但别跳步——先把 skill 用熟理解 agent 的行为模式再去写插件会顺很多。7. 我踩过的几个真实坑和对应的解法第一个坑是skill 之间互相覆盖。我同时写了代码简洁优先和代码可读性优先两个 skill结果 agent 一会儿精简一会儿啰嗦行为很不稳定。后来合并成一个 skill在里面写清楚默认简洁但涉及公共 API 时优先可读性问题就解决了。教训是互相矛盾的 skill 不能共存要么合并要么明确优先级。第二个坑是skill 正文写成了教程。我一开始把某个 skill 写成了 3000 字的完整教程结果 agent 每次加载都吃一大堆 token而且真正关键的约束被淹没在细节里。后来砍到 800 字只留约束和示例遵循率反而上升了。skill 不是文档是给 agent 的行动指令越精炼越好。第三个坑是忽略了 skill 的加载顺序。有些工具里 skill 是按字母序或者目录序加载的后面的可能覆盖前面的。我有个 skill 一直不生效查了半天发现是被同名的另一个 skill 覆盖了。现在我会给 skill 加统一前缀比如team-、proj-避免命名冲突。第四个坑是在旧会话里测试新 skill。前面提过但值得再强调一次。skill 改动后必须新开会话这是硬性要求。我因为这个浪费过整整一个下午反复怀疑 skill 写错了其实只是没重启。提示如果你在用cc switch之类的多环境切换工具注意不同环境可能加载不同的 skill 集合。切换环境后先确认当前生效的 skill 列表再开始干活。8. 关于 skills 后续可以怎么玩skill 用熟之后能玩的花样其实不少。一个方向是把 skill 和项目模板绑定新建项目时自动带上对应的 skill 集合省去每次手动配置。另一个方向是做 skill 的按需组合根据当前任务类型动态加载不同的 skill 子集而不是一股脑全加载。还有个我觉得挺有意思的方向是用 skill 沉淀踩坑经验。每次线上出问题复盘完之后把下次遇到类似情况该怎么排查写成一个 skill日积月累就是团队的排错知识库。这比写文档有用因为 agent 会在你真正遇到问题时主动把它调出来。我个人在实际操作中的体会是skills 这东西写十个不如用好三个。与其追求 skill 数量不如把最核心的两三个打磨到触发准、遵循高、维护省。剩下的精力花在理解 agent 的行为模式上收益更大。毕竟 skill 只是手段让 AI 真正帮你把活干对才是目的。