★ FEATURED ARTICLE 1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术社区还是开发者群聊里“skills”这个词出现的频率高得离谱。你随便翻一下热搜词列表能看到claude code、codex、agents、plugin、agent skills测试、codex skills、claude agent skills: a first principles deep dive这些词反复出现。很多人第一反应是这不就是个“技能”吗有什么好聊的但真正上手用过 Claude Code 或者 Codex 的人会明白这里的 skills 不是抽象概念而是一套实实在在的、可复用、可组合的能力封装机制。我先把话说直白一点skills 本质上就是给 AI 编程助手agent准备的“技能包”。你可以把它理解成手机里的 App——手机本身能打电话、能上网但真正让它变得好用、能解决具体问题的是你装的那些 App。Claude Code、Codex 这些工具本身提供了基础的对话、代码生成、文件读写能力而 skills 就是让它们学会“做某件具体事情”的插件式扩展。那它解决了什么问题核心就三个第一重复劳动的问题。你每次让 AI 帮你写一个 React 组件都要重新解释项目规范、目录结构、命名习惯烦不烦skills 可以把这些规则固化下来一次配置次次生效。第二能力边界的问题。原生 agent 只会通用操作但你要它去调用某个内部 API、执行某个特定构建流程、按照团队规范生成测试用例它不会。skills 就是给它补课。第三一致性的问题。团队里五个人用 AI 写代码五个人得到五种风格。skills 让所有人的 AI 助手遵循同一套标准输出结果可预期。适合谁来研究这个我的判断是凡是日常用 Claude Code、Codex、Cursor 这类 AI 编程工具写代码的人都应该花时间搞懂 skills。尤其是团队里的技术负责人、工具链维护者以及那些想让 AI 真正融入自己工作流而不是当玩具玩的人。小白也能看懂因为我会从最基础的概念讲起但我会假设你至少用过一次 Claude Code 或者 Codex知道它们大概是怎么回事。接下来我会从设计思路、核心机制、实操配置、常见坑四个维度把 skills 这件事彻底讲透。内容基于我自己的使用经验和社区里大量实践者的反馈整理不是官方文档的复述而是“一个天天用的人会怎么想、怎么做”。2. skills 的整体设计与核心思路拆解2.1 为什么是“技能”而不是“配置”或“插件”很多人第一次接触 skills 会问这跟配置文件有什么区别跟 plugin 有什么区别我一开始也这么想后来用多了才理解设计者的意图。配置config是静态的比如你设置一个settings.json告诉工具用哪个模型、超时时间多少。它不包含“怎么做一件事”的逻辑。插件plugin是功能性的比如给编辑器装一个 Git 插件它增加的是工具本身的能力。而skills 介于两者之间它既不是纯配置也不是纯功能而是“面向任务的能力封装”。打个比方配置是你告诉厨师“少放盐”插件是你给厨房添了一台烤箱而 skills 是你给厨师一本菜谱上面写着“做红烧肉要先焯水、再炒糖色、最后小火炖四十分钟”。厨师本身会做饭但有了这本菜谱他就能稳定地做出你想要的这道菜。这个设计思路的好处是skills 是可组合的。你可以有一个“写 React 组件”的 skill一个“写单元测试”的 skill一个“提交代码前检查”的 skill它们可以串联起来形成一个完整的工作流。而配置和插件很难做到这种任务级别的编排。2.2 skills 的核心构成描述、触发、执行拆开来看一个 skill 通常包含三个关键部分描述description告诉 agent 这个 skill 是干什么的、什么时候该用它。这部分极其重要因为 agent 是根据描述来决定是否调用某个 skill 的。描述写得模糊agent 就不知道该不该用。触发条件trigger什么情况下激活这个 skill。可以是用户显式调用也可以是 agent 根据上下文自动判断。比如你输入“帮我写个登录页面”agent 会自动匹配到“前端组件生成”这个 skill。执行逻辑execution具体怎么做。这部分可以是一段提示词prompt也可以是一组操作步骤甚至可以调用外部脚本或工具。我实测下来描述和触发条件的质量直接决定了一个 skill 好不好用。很多人写 skill 只关注执行逻辑结果 agent 根本不知道什么时候该用它等于白写。2.3 与 Claude Code、Codex 的集成方式Claude Code 和 Codex 对 skills 的支持方式略有不同但核心逻辑一致它们都提供了一个 skill 注册机制让你把自定义能力挂载到 agent 上。在 Claude Code 里skills 通常放在特定目录下每个 skill 一个文件夹里面包含描述文件和执行逻辑。Claude Code 启动时会扫描这些目录把可用的 skills 加载进来。当你发出指令时agent 会根据 skill 的描述判断是否调用。Codex 这边skills 的概念更偏向于“可复用的提示模板 工具调用”。你可以把一组常用的操作封装成一个 skill然后在对话中通过特定语法触发。Codex 的 skills 更强调与代码仓库的交互比如“按照项目规范生成 commit message”这种。两者共同的思路是把重复的、有固定套路的任务从“每次重新描述”变成“一次定义、反复调用”。这就是 skills 最大的价值。2.4 为什么现在 skills 这么火我觉得有几个原因叠加在一起一是AI 编程工具本身成熟了。一年前大家还在纠结“AI 写的代码能不能用”现在更多人关心“怎么让 AI 写得符合我的要求”。skills 正好解决后者。二是agent 概念普及了。大家开始理解AI 不只是聊天机器人而是可以执行多步任务的代理。既然是代理就需要“技能”来扩展能力边界。三是社区生态起来了。热搜词里能看到claude 国内安装skills 官方市场、codex好用的skills、skills推荐这些说明已经有人在分享、在推荐、在讨论哪些 skills 好用。有生态就有动力。四是企业级需求驱动。团队用 AI 写代码最怕风格不统一、质量不可控。skills 提供了一种标准化的手段让 AI 的输出可预期、可审计。3. 核心细节解析与实操要点3.1 skill 的描述怎么写才有效这是我最想强调的一点。描述不是写给人看的是写给 agent 看的。所以它的写法跟普通文档完全不同。一个有效的描述应该包含任务类型这个 skill 处理什么类型的任务。比如“生成 React 函数组件”。触发场景什么情况下应该用。比如“当用户要求创建新的 UI 组件时”。输入要求需要用户提供什么信息。比如“组件名称、props 定义、样式要求”。输出格式产出什么。比如“一个 .tsx 文件包含类型定义和样式”。我见过太多人把描述写成“这是一个很好用的 skill”这种描述 agent 看了等于没看。描述要具体、可判断、有边界。提示描述里避免用“可能”“也许”“根据需要”这类模糊词。agent 需要明确的判断依据模糊描述会导致误触发或漏触发。3.2 触发机制的设计技巧触发机制分两种显式触发和隐式触发。显式触发就是用户明确说“用某某 skill”。这种方式简单直接但需要用户记住 skill 的名字体验不够顺滑。隐式触发是 agent 根据上下文自动判断。这种方式体验好但对描述质量要求极高。我的经验是先用显式触发跑通流程再逐步优化描述让隐式触发也能准确工作。一个实用技巧是在描述里加入“反例”。比如“这个 skill 用于生成 React 组件不用于生成 Vue 组件”。这样 agent 在遇到 Vue 相关请求时就不会误触发。另一个技巧是给 skill 起一个语义明确的名字。react-component-gen比component-helper好因为前者一看就知道干什么后者太泛。3.3 执行逻辑的三种写法执行逻辑可以很简单也可以很复杂。我把它分成三种第一种纯提示词。就是一段自然语言指令告诉 agent 怎么做。适合逻辑简单、不需要外部工具的场景。比如“生成一个符合 Airbnb 规范的 ESLint 配置”。第二种提示词 模板。在提示词基础上提供输出模板。比如“按照以下模板生成组件文件先 import再类型定义再组件函数最后 export”。这种方式能保证输出结构一致。第三种提示词 脚本调用。最复杂但最强大。skill 可以调用外部脚本比如运行一个代码生成器、调用一个 API、执行一个构建命令。这种方式适合需要与外部系统交互的场景。我的建议是从第一种开始够用就不升级。很多人一上来就想搞最复杂的结果维护成本高得吓人。skills 的核心价值是“稳定复用”不是“功能炫酷”。3.4 目录结构与文件组织一个典型的 skill 目录结构是这样的skills/ react-component/ skill.md # 描述和触发条件 prompt.md # 执行逻辑 templates/ component.tsx # 输出模板 unit-test/ skill.md prompt.mdskill.md放描述和触发条件prompt.md放具体执行逻辑templates/放模板文件。这种分离的好处是修改描述不影响执行逻辑修改执行逻辑不影响描述。有些实现会把所有内容放在一个文件里用 frontmatter 区分。两种方式都行关键是保持一致性。团队里用哪种就统一用哪种别混着来。3.5 参数化与动态输入好的 skill 不是死板的而是能接受参数的。比如“生成组件”这个 skill应该能接受组件名称、props 列表、样式方案等参数。参数化的实现方式通常是在提示词里用占位符比如{{componentName}}、{{props}}。agent 在调用时会把实际值填进去。这里有个坑参数太多会导致 agent 不知道该填什么。我的经验是一个 skill 的参数控制在 3 到 5 个以内。超过这个数就应该拆成多个 skill或者让 skill 自己去推断。注意参数命名要清晰。name不如componentNamestyle不如styleSolution。agent 对命名的敏感度比你想象的高。4. 实操过程与核心环节实现4.1 环境准备Claude Code 与 Codex 的 skills 目录先说 Claude Code。安装完成后skills 通常放在用户目录下的.claude/skills/或者项目目录下的.claude/skills/。前者是全局 skill所有项目都能用后者是项目级 skill只对当前项目生效。我建议通用型 skill 放全局项目特定 skill 放项目目录。比如“生成 commit message”这种通用 skill 放全局“生成这个项目的 API 客户端”放项目目录。Codex 这边skills 的存放位置取决于你用的是哪个版本。较新的版本支持在项目根目录下创建.codex/skills/目录。具体路径建议查一下你所用版本的文档因为这块变化比较快。配置完成后重启工具让它重新扫描 skills 目录。有些版本支持热加载有些不支持。不确定的时候重启是最稳妥的。4.2 从零写一个 skill以“生成 React 组件”为例我来完整走一遍流程。第一步创建目录mkdir -p .claude/skills/react-component/templates第二步写描述文件skill.md--- name: react-component description: 生成符合项目规范的 React 函数组件。当用户要求创建新的 UI 组件、页面片段或可复用 React 组件时使用。不适用于 Vue、Angular 或其他框架。 trigger: - 用户要求创建 React 组件 - 用户要求生成 UI 组件 - 用户提到 .tsx 文件创建 ---这里我特意加了“不适用于 Vue、Angular”就是为了防止误触发。第三步写执行逻辑prompt.md请按照以下规范生成 React 函数组件 1. 使用 TypeScript文件扩展名为 .tsx 2. 组件名使用 PascalCase 3. Props 使用 interface 定义命名为 {{componentName}}Props 4. 样式使用 CSS Modules文件名与组件同名 5. 导出使用 named export不使用 default export 6. 组件内部先写类型定义再写组件函数 组件名称{{componentName}} Props 列表{{props}} 样式要求{{styleRequirement}}第四步添加模板templates/component.tsximport styles from ./{{componentName}}.module.css; export interface {{componentName}}Props { {{props}} } export function {{componentName}}({}: {{componentName}}Props) { return ( div className{styles.container} {/* 组件内容 */} /div ); }第五步测试在 Claude Code 里输入“帮我创建一个 UserCard 组件接收 name 和 avatar 两个 props”。观察 agent 是否自动调用了这个 skill输出是否符合规范。我实测下来第一次通常不会完美。可能需要调整描述、补充触发词、修改模板。迭代两三次是正常的。4.3 参数传递与模板渲染的细节参数传递这块有几个细节值得说。占位符格式要统一。有的实现用{{param}}有的用${param}有的用[param]。选定一种全项目统一。混用会导致渲染失败。默认值处理。不是所有参数都必须传。可以在提示词里写“如果未提供样式要求默认使用 CSS Modules”。这样 agent 就知道怎么处理缺失参数。参数校验。如果某个参数是必须的在描述里写清楚“必须提供组件名称”。agent 在缺少参数时会主动询问用户而不是瞎猜。模板渲染的边界情况。如果参数值包含特殊字符比如、、可能会破坏模板结构。我的做法是在提示词里提醒 agent 对特殊字符做转义或者在模板里用安全的方式插入。4.4 多 skill 组合与工作流编排单个 skill 好用但真正强大的是组合。举个例子我有三个 skill——react-component生成组件、unit-test生成测试、lint-check检查代码规范。我可以让 agent 按顺序执行先生成组件再生成测试最后跑 lint 检查。组合的方式有两种一种是链式调用。用户说“创建一个 UserCard 组件并生成测试”agent 先调用react-component再调用unit-test。另一种是嵌套调用。unit-testskill 内部可以引用react-component的输出作为输入。我建议先从链式调用开始因为逻辑清晰、容易调试。嵌套调用虽然灵活但出问题时很难定位是哪个环节的锅。提示组合 skill 时注意输出格式的兼容性。前一个 skill 的输出要能被后一个 skill 正确解析。最好在描述里明确输入输出格式。4.5 在 Codex 中配置 skills 的实操记录Codex 的 skills 配置跟 Claude Code 略有不同。我以较新版本为例。首先在项目根目录创建.codex/skills/目录。然后每个 skill 一个子目录里面放config.json和prompt.md。config.json大概长这样{ name: api-client-gen, description: 根据 OpenAPI 规范生成 TypeScript API 客户端, triggers: [生成 API 客户端, 根据接口文档生成代码], parameters: [specPath, outputDir] }prompt.md里写具体逻辑可以引用参数。配置完成后在 Codex 对话里输入“根据 docs/openapi.yaml 生成 API 客户端到 src/api/”agent 应该能识别并调用。我踩过的坑是Codex 对触发词的匹配比较严格。如果用户说的词跟triggers里的不完全一致可能不会触发。解决办法是多写几个同义词比如“生成 API 客户端”“创建 API 客户端”“根据接口文档生成代码”都写上。5. 常见问题与排查技巧实录5.1 skill 不触发怎么办这是最高频的问题。排查思路如下可能原因排查方法解决方案描述不清晰检查description是否具体补充任务类型和触发场景触发词不匹配对比用户输入和triggers增加同义词和变体目录位置错误确认 skills 目录路径放到正确的全局或项目目录未重启工具检查是否重新加载重启 Claude Code 或 Codex优先级冲突是否有其他 skill 抢先匹配调整描述增加区分度我的经验是八成问题出在描述上。描述写得太泛agent 不知道什么时候该用写得太窄又匹配不到。多写几个具体场景比写一堆抽象词有用。5.2 skill 触发了但输出不对这种情况通常是执行逻辑的问题。排查方向提示词是否明确有没有说清楚步骤、格式、约束。模板是否正确占位符有没有写错模板文件是否被正确加载。参数是否传对agent 填进去的值是否符合预期。上下文是否干扰对话历史里有没有冲突信息。我遇到过一次skill 生成的组件总是缺少类型定义。查了半天发现是提示词里写了“生成组件”但没写“包含类型定义”。agent 就按最简方式生成了。提示词要写到“傻瓜都能执行”的程度别假设 agent 会自己补全。5.3 多个 skill 冲突怎么处理当两个 skill 的描述有重叠时agent 可能随机选一个或者选错。解决办法第一明确边界。在描述里写清楚“这个 skill 用于 X不用于 Y”。第二设置优先级。有些实现支持在配置里指定优先级数字大的优先。第三合并 skill。如果两个 skill 经常一起用考虑合并成一个减少冲突。第四用显式触发。在关键场景下让用户明确指定用哪个 skill避免歧义。5.4 性能问题skill 太多会不会变慢会。每个 skill 都需要 agent 在决策时进行评估。skill 数量多了决策时间会变长误触发概率也会增加。我的建议是全局 skill 控制在 10 个以内项目级 skill 控制在 5 个以内。超过这个数就要考虑合并或归档。另外定期清理不用的 skill。我每两周会 review 一次 skills 目录把一个月没用过的删掉或移到归档目录。保持精简比堆数量重要。5.5 团队协作中的 skill 管理团队用 skills最大的问题是版本不一致。张三改了 skill李四不知道结果两人用 AI 生成的代码风格不一样。我的做法是把 skills 目录纳入版本控制。跟代码一样skill 的修改也要走 PR、要 review。这样谁改了什么、为什么改都有记录。另外给 skill 写变更日志。在skill.md里加一个changelog段落记录每次修改的内容和原因。这样新人接手时能快速了解来龙去脉。注意不要把个人偏好的 skill 放进团队共享目录。团队 skill 应该是“大家都认可的标准”而不是“某个人觉得好用”。5.6 常见错误速查表错误现象可能原因快速修复skill 完全不触发目录路径错误检查.claude/skills/或.codex/skills/触发但输出为空模板文件缺失确认templates/下有对应文件参数未替换占位符格式不匹配统一使用{{param}}格式输出格式混乱提示词缺少格式约束在提示词里明确输出结构多个 skill 抢触发描述边界模糊增加“不适用于”说明修改后不生效未重启工具重启 Claude Code 或 Codex团队风格不一致skill 未纳入版本控制把 skills 目录加入 Git6. 进阶玩法让 skills 真正融入日常工作流6.1 把 skills 和 Git hooks 结合我试过一个挺有意思的玩法把 skill 跟 Git hooks 结合。比如在pre-commit里调用一个 skill让它检查即将提交的代码是否符合规范。具体做法是写一个 skill 叫pre-commit-check描述是“检查代码是否符合项目规范”。然后在.git/hooks/pre-commit里调用 Claude Code 或 Codex 的命令行接口传入变更文件列表让 agent 执行这个 skill。这样每次提交前AI 都会自动检查一遍。发现问题就阻止提交并给出修改建议。实测下来能拦住不少低级错误。6.2 用 skills 做代码审查代码审查是 skills 的绝佳应用场景。你可以写一个code-reviewskill描述是“对指定文件进行代码审查检查命名规范、潜在 bug、性能问题”。然后在 PR 流程里让 agent 自动对变更文件跑这个 skill把审查结果作为评论贴到 PR 上。这样人工审查者只需要关注业务逻辑不用再纠结格式问题。我自己的项目里这个 skill 帮我省了不少时间。尤其是那些“忘了处理边界情况”“变量命名不一致”的问题AI 比人眼更敏感。6.3 skills 的版本管理与团队共享前面提过要把 skills 纳入版本控制这里展开说一下具体怎么做。目录结构建议project/ .claude/ skills/ shared/ # 团队共享 skill react-component/ unit-test/ local/ # 个人 skill不提交 my-experiment/.gitignore里排除local/目录只提交shared/。这样个人实验不影响团队团队标准又能统一。版本管理策略主分支上的 skills 是稳定版所有人可用。新 skill 先在 feature 分支开发测试通过后合并。重大修改要写迁移说明通知团队成员。共享方式除了 Git还可以把 skills 打包成 npm 包或内部工具包通过包管理器分发。这种方式适合跨项目复用。不过要注意版本兼容性不同项目的 Claude Code 版本可能不同。6.4 从社区获取现成 skills 的注意事项热搜词里有claude 国内安装skills 官方市场、codex好用的skills、skills推荐说明社区里已经有不少现成 skill 可以拿来用。我的建议是可以用但要审查。拿到一个别人的 skill先看它的描述是否清晰、执行逻辑是否合理、有没有安全隐患。尤其是那些会调用外部脚本或 API 的 skill一定要确认它做了什么。另外不要直接复制到团队目录。先放到个人目录测试确认好用再推荐给团队。每个人的工作流不同别人觉得好用的你不一定适用。6.5 skills 的未来扩展方向从目前的发展趋势看skills 这块还在快速演进。我观察到几个方向一是标准化。不同工具的 skill 格式可能会趋同形成事实标准。这样写一次 skill多个工具都能用。二是市场化和分发机制。类似 App Store 的 skill 市场可能会出现让 skill 的分享和获取更便捷。三是与 CI/CD 深度集成。skills 不只是开发时的辅助还可能进入构建、测试、部署流程成为自动化的一部分。四是智能化触发。未来的 agent 可能不需要显式触发词而是根据上下文更精准地判断该用哪个 skill。这些方向不一定都会实现但值得关注。对于日常使用者来说先把基础用法跑通再逐步跟进新特性是比较稳妥的策略。7. 我个人的一些实操体会写了这么多最后分享几点我自己的体会不是教程就是踩坑之后的真实感受。第一skill 的质量比数量重要得多。我一开始兴致勃勃写了二十多个 skill结果常用的就三四个。剩下的要么描述不清不触发要么触发后输出不对反而添乱。后来我砍到八个每个都反复打磨效率反而高了。第二描述值得花时间打磨。我写第一个 skill 时描述只写了一句“生成 React 组件”结果 agent 经常在该用的时候不用不该用的时候乱用。后来我把描述改成“当用户要求创建新的 UI 组件、页面片段或可复用 React 组件时使用不适用于 Vue、Angular”触发准确率立刻上来了。描述是 skill 的灵魂别在这上面偷懒。第三从简单开始别一上来就搞复杂。我见过有人第一个 skill 就想调用外部 API、跑构建脚本、生成完整模块。结果调试了一周还没跑通直接放弃了。我的建议是第一个 skill 就写“生成一个符合规范的配置文件”这种最简单的跑通流程、建立信心再逐步加复杂度。第四团队共享要谨慎。个人觉得好用的 skill别人不一定觉得好用。我推过一个“自动生成 commit message”的 skill 给团队结果有人觉得生成的 message 太啰嗦有人觉得太简略。后来改成可配置的才勉强达成一致。团队 skill 要留出配置空间别把个人偏好写死。第五定期清理。skill 跟代码一样会腐化。项目变了、规范变了、工具版本变了skill 可能就失效了。我每两周会花十分钟 review 一遍把不用的删掉把过时的更新。这个习惯帮我避免了很多“为什么 AI 输出不对”的困惑。第六别指望 skill 解决所有问题。skills 是工具不是银弹。有些任务就是需要人工判断有些场景就是不适合自动化。知道什么时候不用 skill比知道怎么用 skill 更重要。最后再分享一个小技巧如果你不确定一个 skill 该怎么写先手动做一遍任务把步骤记下来再把步骤翻译成提示词。这个方法我用了很多次比凭空想要靠谱得多。手动做的时候你会自然发现哪些步骤是关键、哪些容易出错、哪些需要参数化。把这些观察写进 skill质量不会差。
阅读完成 · 觉得有帮助？
