1. 从skills这个模糊词说起它到底指什么第一次看到skills这个标题很多人会懵。它太短、太泛像是随手敲下的一个词。但结合热搜词里反复出现的 Claude Code、Codex、plugin、agents 这些词方向其实很明确——这里说的 skills指的是围绕 AI 编程助手尤其是 Claude Code 和 Codex 这类命令行 Agent 工具构建的可复用能力单元。你可以把它理解成给 AI 助手装的技能包。一个 skill 通常是一段结构化的指令、一个脚本、一套工作流模板或者几者的组合。它的作用是让 AI 在面对特定任务时不用你每次从头解释而是直接调用预设好的能力去干活。比如帮我生成一份符合团队规范的 commit message把这个 JSON 转成 TypeScript 类型定义按我们的目录结构新建一个 React 组件——这些重复性动作都可以封装成一个 skill。为什么这个概念最近突然火了因为 Claude Code 和 Codex 这类工具把 AI 编程从聊天窗口推进到了终端里的自主 Agent。Agent 能读写文件、执行命令、跑测试能力边界一下打开了。但随之而来的问题是通用 Agent 什么都能干一点却什么都不精。你让它写代码它写得还行你让它按你团队的规范写代码它就开始自由发挥。skills 就是来解决这个最后一公里问题的。这篇文章适合谁看三类人。第一类是把 Claude Code 或 Codex 当日常开发工具用的人想知道怎么让它更听话、更贴合自己的项目。第二类是团队里的技术负责人想把团队的编码规范、工作流固化下来让 AI 助手成为团队生产力的一部分。第三类是对 Agent 架构感兴趣、想自己动手做 skill 开发的人。不管你是哪一类下面这些内容都是从实际使用和踩坑中攒出来的不是文档的复述。需要先说明一点skills 目前没有统一的官方标准Claude Code 有自己的 skill 机制Codex 有另一套社区里还有各种第三方插件市场。所以我会把重点放在通用的设计思路和实操方法上具体到某个工具的配置细节会分别说明。这样你换工具的时候思路是能迁移的。2. Claude Code 的 skill 机制从安装到第一个可用技能2.1 安装 Claude Code 时最容易忽略的环境问题Claude Code 的安装本身不复杂但环境问题是最常见的拦路虎。官方推荐的方式是通过 npm 全局安装命令大致是npm install -g anthropic-ai/claude-code。装完之后在终端敲claude就能启动。听起来简单但实际装的时候下面这几个坑几乎人人都会踩一遍。第一个坑是 Node 版本。Claude Code 对 Node 版本有要求太老的版本会直接报错退出。我建议直接用 Node 18 或更高版本如果你机器上有 nvm先nvm install 18 nvm use 18再装。第二个坑是权限。全局安装在某些系统上需要 sudo但用 sudo 装完之后普通用户运行时又可能遇到权限问题。更稳妥的做法是配置 npm 的全局目录到用户目录下避免权限纠缠。第三个坑是网络。安装过程需要从 npm registry 拉包如果你的网络环境访问不稳定安装会卡住或者超时。这时候可以配置国内镜像源比如npm config set registry https://registry.npmmirror.com装完再切回去。这个操作对安装速度的提升非常明显实测下来能从几分钟缩短到几十秒。装完之后第一次运行claude会引导你做认证。认证方式这里不展开按提示走就行。认证通过后你会进入一个交互式终端界面这就是 Claude Code 的主战场。2.2 skill 的目录结构与加载逻辑Claude Code 的 skill 本质上是一些放在特定目录下的文件。默认情况下它会从几个位置加载 skill项目根目录下的.claude/skills/目录、用户主目录下的~/.claude/skills/目录以及一些内置的 skill。项目级的 skill 只对当前项目生效用户级的 skill 对你所有项目生效。这个设计很合理——团队规范放项目级个人习惯放用户级。一个 skill 通常是一个目录里面至少有一个描述文件一般是 markdown 或 yaml 格式说明这个 skill 叫什么、什么时候触发、具体做什么。有些复杂的 skill 还会带脚本文件比如一个 Python 脚本或者 shell 脚本用来执行具体的操作。加载逻辑是这样的当你给 Claude Code 发一条指令它会先判断这条指令是否匹配某个 skill 的触发条件。如果匹配它就会加载对应的 skill 内容把里面的指令和你的原始请求结合起来再决定怎么执行。所以 skill 的触发条件写得越精准误触发的概率就越低。这里有个经验不要把触发条件写得太宽泛。我见过有人写了一个代码审查的 skill触发词设成review结果每次他说review 一下这个 PR和review 一下我的简历都会触发同一个 skill后者就完全跑偏了。触发词要具体最好带上领域限定比如审查代码检查这个函数。2.3 写第一个 skill从生成 commit message开始理论说再多不如动手。我们拿一个最实用的场景练手自动生成符合规范的 commit message。先创建目录在项目根目录下建.claude/skills/commit-helper/。然后在这个目录里创建一个SKILL.md文件内容大致是这样--- name: commit-helper description: 当用户要求生成 commit message 或提交代码时使用 --- 当用户要求生成 commit message 时请按以下步骤操作 1. 运行 git diff --staged 查看暂存区的改动 2. 分析改动内容判断是 feat、fix、docs、refactor、test 还是 chore 3. 按 Conventional Commits 规范生成 message格式为type(scope): description 4. description 用中文不超过 50 字 5. 如果改动涉及多个类型拆分成多条 commit 建议 不要直接执行 git commit先把建议的 message 展示给用户确认。这个 skill 的关键点在于它明确告诉 AI 去跑什么命令、按什么规则判断、输出什么格式、以及不要做什么。最后那条不要直接执行 commit特别重要因为 Agent 默认是有执行能力的你不限制它它可能真的帮你提交了而你可能还没准备好。写完这个文件重启 Claude Code然后输入帮我生成 commit message它就会自动加载这个 skill 并按流程走。第一次跑通之后你会明显感觉到AI 的输出从随机发挥变成了按规矩办事。2.4 skill 的调试与迭代怎么知道它有没有生效skill 写完不生效是新手最常遇到的问题。排查思路可以按这个顺序来。先确认文件位置对不对。项目级 skill 必须在.claude/skills/下用户级在~/.claude/skills/下目录名和文件名都不能错。然后确认格式对不对frontmatter 里的 name 和 description 是必须的缺了可能加载不了。再确认触发条件——你输入的指令是否真的匹配了 description 里描述的场景。如果这些都对了还是不生效可以在 Claude Code 里直接问它你现在加载了哪些 skill它一般会列出来。如果列表里没有你的 skill那就是加载环节出了问题如果有但没触发那就是触发条件的问题。调试 skill 有个技巧把 description 写得稍微主动一点。比如不要写用于生成 commit message而是写当用户提到 commit、提交、message 时使用。前者是描述功能后者是描述触发场景后者更容易被匹配到。3. Codex 的 skill 生态和 Claude Code 有什么不同3.1 Codex 的定位差异决定了 skill 的写法不同Codex 和 Claude Code 虽然都是命令行 AI 编程工具但定位有差异。Claude Code 更偏向全能型 Agent什么任务都能接Codex 在代码生成和补全上的专注度更高和编辑器的集成也更紧密。这个差异直接影响了 skill 的设计思路。在 Claude Code 里skill 更像是一套工作流指令告诉 Agent 按什么步骤做事。在 Codex 里skill 更偏向代码上下文增强比如告诉它在生成代码时要遵循什么风格、引用哪些内部库、避免哪些模式。所以如果你要从 Claude Code 迁移 skill 到 Codex不能直接复制得重新组织内容。Codex 的 skill 配置通常放在项目的配置文件里或者通过插件机制加载。它支持自定义指令模板你可以在模板里嵌入项目特定的规则。比如你可以定义一个模板让 Codex 在生成 React 组件时自动使用你们团队的组件库而不是自己造轮子。3.2 用 Codex 接入本地模型时的 skill 适配热搜词里有个codex 接入 deepseek和claude code 调用 lmstudio 的本地模型说明很多人想把这类工具接到本地或第三方模型上。这个需求很实际——本地模型响应快、数据不出本地、成本可控。但接入本地模型后skill 的行为可能会变。因为不同模型对指令的遵循程度不一样。Claude 系列模型对复杂指令的遵循度很高你写一套多步骤的 skill它能老老实实按步骤走。但一些较小的本地模型指令一长就容易忘记前面的要求。这时候 skill 要写得更简洁、更结构化把关键约束放在最前面。我的做法是为不同模型准备不同版本的 skill。给强模型的版本可以详细包含背景说明和示例给弱模型的版本只保留核心步骤和硬性约束用编号列表一条一条列清楚。这样切换模型的时候skill 的可靠性不会掉太多。3.3 Codex 安装与配置中的常见报错处理Codex 安装过程中报错信息往往比较晦涩。有几个高频问题值得单独说。一个是无法加载组织设置这类错误。这通常和认证配置有关检查一下你的配置文件路径是否正确token 是否过期。另一个是插件加载失败报错里可能提到某个 plugin 找不到。这时候先确认插件是否真的装了再确认插件版本和 Codex 版本是否兼容。版本不匹配是插件类问题最常见的原因。还有一个容易被忽略的点工作目录。Codex 和 Claude Code 都会以当前工作目录为基准来加载项目级配置。如果你在错误的目录下启动它就读不到你的 skill。养成习惯启动前先pwd确认一下位置。4. skill 设计的核心原则让 AI 真正听话4.1 指令要可执行不要可理解这是我在写了十几个 skill 之后最大的体会。很多人写 skill 的时候习惯用人类之间的沟通方式写一堆背景说明和期望。但 AI 不需要你解释为什么它需要你告诉它做什么和怎么做。举个例子。差的写法是我们希望 commit message 能够清晰地反映改动内容方便团队成员理解。好的写法是运行 git diff --staged按 Conventional Commits 规范生成 messagetype 从 feat/fix/docs/refactor/test/chore 中选description 用中文不超过 50 字。前者是期望后者是指令。AI 对后者的执行准确率远高于前者。所以写 skill 的时候把每一句话都问自己一遍这句话是在描述期望还是在给出可执行的指令如果是前者改掉。4.2 边界条件比主流程更重要一个 skill 的主流程通常好写难的是边界条件。比如生成 commit message这个 skill主流程就是看 diff、判断类型、生成 message。但边界情况很多diff 为空怎么办改动涉及多个不相关模块怎么办改动里有敏感信息怎么办这些边界如果不写清楚AI 遇到时就会自由发挥而自由发挥的结果往往不可控。我的习惯是在 skill 里专门留一段异常处理把能想到的边界情况都列出来给出明确的处理方式。比如如果 diff 为空提示用户先暂存改动不要生成 message。4.3 用禁止清单约束 AI 的越界行为Agent 类工具最大的风险是自作主张。你让它生成代码它可能顺手帮你改了别的文件你让它分析问题它可能直接动手修了。所以在 skill 里明确列出禁止事项和列出允许事项同样重要。常见的禁止项包括不要自动执行 git commit/push、不要修改 skill 范围外的文件、不要安装依赖、不要访问网络。这些约束看起来保守但能避免很多意外。等你对某个 skill 足够信任了再逐步放开权限。5. 从零搭建一套团队级 skill 体系的实操路径5.1 先盘点重复劳动再决定做哪些 skill不要一上来就想做一套大而全的 skill 体系。正确的顺序是先观察团队里哪些动作是重复的、耗时的、容易出错的然后针对这些动作做 skill。我一般会花一周时间记录自己和团队的日常工作把重复性动作列出来。常见的候选包括新建组件/模块、写单元测试、生成 API 文档、代码审查、生成 changelog、处理国际化文案。这些动作的共同点是有固定套路、有明确规范、每次做都要重复解释。盘点完之后按频率 × 耗时排序先做排名靠前的。不要贪多一次做一个做完一个用一周确认稳定了再做下一个。5.2 skill 的版本管理与团队共享skill 是代码资产应该纳入版本管理。我的做法是在项目仓库里建一个.claude/skills/目录把 skill 文件提交进去。这样团队成员拉下代码就自动有了这套 skill不需要每个人单独配置。但要注意skill 里不要放敏感信息比如 API key、内部地址。这些应该通过环境变量注入而不是硬编码在 skill 文件里。另外skill 的修改应该走 code review因为一个写得不好的 skill 会影响所有人的使用体验。团队共享还有个好处skill 会自然演化。张三用的时候发现某个边界没处理提个 PR 补上李四发现某个步骤可以优化也提个 PR。几个月下来这套 skill 会变得非常贴合团队的实际需求这是任何通用工具都做不到的。5.3 用 skill 测试来保证可靠性skill 写多了之后怎么保证每个都还能正常工作答案是写测试。skill 的测试不需要很复杂核心是验证给定输入AI 是否按预期执行。可以准备一组测试用例每个用例包含一条用户指令和期望的行为。然后定期跑一遍看 AI 的输出是否符合预期。如果某个 skill 的测试开始失败说明要么 skill 文件被改坏了要么模型行为变了需要排查。这个做法在模型升级的时候特别有用。模型一升级行为可能有微妙变化之前好用的 skill 可能就不灵了。有测试兜底你能第一时间发现问题而不是等用户反馈。6. 那些没人告诉你但一定会踩的坑6.1 skill 之间的冲突触发词重叠的连锁反应当你有了多个 skill 之后冲突就来了。最常见的是触发词重叠。比如你有一个代码审查skill 和一个代码重构skill两者的触发词都包含代码那用户说帮我看看这段代码的时候到底触发哪个解决方法是给每个 skill 划定清晰的领域边界触发词尽量不重叠。如果实在避不开就在 skill 里加优先级说明或者在 description 里写清楚仅当用户明确要求审查时使用。另一个办法是给 skill 加命名空间比如review:code和refactor:code用户调用时带上前缀就不会歧义了。6.2 模型升级导致 skill 失效的应对模型升级是双刃剑。新模型通常更强但行为模式可能变。我遇到过好几次一个 skill 在旧模型上跑得好好的模型一升级输出格式就变了因为新模型更聪明觉得你的格式要求可以优化。应对方法有两个。一是 skill 里的格式要求写得更强硬用必须严格按以下格式这类词减少模型的自由发挥空间。二是建立回归测试模型升级后先跑一遍测试看哪些 skill 受影响再针对性调整。不要等出了问题才被动应对。6.3 本地模型场景下 skill 的降级策略用本地模型的时候skill 的可靠性会下降。因为本地模型通常比云端大模型弱对复杂指令的遵循度不够。这时候要有降级策略。我的做法是给每个 skill 准备两个版本完整版和精简版。完整版给强模型用包含详细步骤和示例精简版给弱模型用只保留最核心的指令用短句和编号列表。启动时根据当前使用的模型自动选择版本。这样即使换了模型skill 的基本功能还在。6.4 权限失控Agent 做了你没让它做的事这是最危险的坑。Agent 有执行能力如果你没在 skill 里限制它它可能做出意料之外的操作。我听说过有人让 AI清理一下项目里的临时文件结果 AI 把整个 build 目录删了因为那些文件看起来像临时的。防范措施有三条。第一skill 里明确列出禁止操作尤其是删除、提交、推送这类不可逆操作。第二重要操作要求 AI 先展示计划等用户确认后再执行。第三定期检查 AI 的操作日志看看有没有越界行为。这三条做到位基本能避免大部分事故。7. skill 开发的进阶方向7.1 让 skill 具备组合能力单个 skill 的能力有限真正强大的是 skill 的组合。比如新建组件skill 可以调用生成测试skill 和更新文档skill形成一个完整的工作流。用户只需要说一句新建一个 UserCard 组件背后自动完成组件文件创建、测试生成、文档更新、导出配置修改等一系列动作。实现组合的关键是定义好 skill 之间的接口。每个 skill 的输入输出要标准化这样上游 skill 的输出能直接作为下游 skill 的输入。这个思路和函数式编程里的组合很像做起来不难但需要提前规划。7.2 基于项目上下文动态调整 skill 行为好的 skill 应该能感知项目上下文。比如同样是生成测试skill在 React 项目里生成的是组件测试在 Node 项目里生成的是接口测试。实现方式是让 skill 先读取项目配置文件比如 package.json判断项目类型再选择对应的测试模板。这个能力让 skill 从死规则变成活规则适应性大大增强。代价是 skill 会变复杂需要更多的条件判断。我的建议是先做简单版本等用出问题了再逐步加条件不要一开始就追求大而全。7.3 skill 的可观测性知道它什么时候被用了skill 用多了之后你会想知道哪些 skill 最常用哪些几乎没人用哪些经常失败这些信息对优化 skill 体系很重要。可以在 skill 里加日志记录每次触发时写一条日志记录时间、用户、输入、结果。积累一段时间后分析这些日志就能看出使用模式。常用的 skill 重点维护没人用的考虑删掉经常失败的优先修复。这个做法借鉴了产品运营的思路用在 skill 管理上同样有效。8. 我个人的一些使用体会写了这么多 skill最大的感受是skill 的价值不在于多而在于精。我见过有人一口气写了三十个 skill结果常用的就三五个剩下的都是摆设。与其铺量不如把最常用的那几个打磨到极致让它们真正融入日常工作流。另一个体会是skill 要跟着项目一起演化。项目变了规范变了skill 也要跟着改。我现在的习惯是每次项目有重大调整就顺手检查一遍相关 skill该更新的更新该废弃的废弃。这样 skill 体系不会随着时间腐化。最后说个实用的从最简单的 skill 开始。不要一上来就挑战复杂的工作流先做一个生成 commit message或者格式化代码这种小 skill跑通了、用顺了再逐步加复杂度。这个过程能帮你建立对 skill 机制的直觉后面做复杂 skill 的时候会顺利很多。skill 这个方向还在快速演化工具在变最佳实践也在变。但核心逻辑是不变的把重复的、有规范的工作固化下来让 AI 按你的方式干活而不是按它自己的方式。抓住这个核心具体用什么工具、什么格式都是次要的。