1. 这套工作流到底在解决什么问题第一次看到AI-Infra-Auto-Driven-SKILLS这个名字很多人会以为是某个新出的推理框架或者模型压缩工具。实际上它跟模型本身没太大关系它是一套给 Codex 和 Claude Code 这类命令行 AI 编码助手用的技能编排层。说白了就是把你平时反复手动敲的那些提示词、检查清单、代码规范、项目约定打包成一个个可复用的 SKILL让 AI 在合适的时机自动加载、自动执行。我用了大概两周时间把这套东西跑通中间踩了不少坑也总结出一些文档里不会写的经验。这篇文章就把整个思路、实现细节、实操步骤和排查技巧完整拆一遍适合两类人看一是已经在用 Codex 或 Claude Code 但觉得每次都要重复交代背景、效率上不去的开发者二是想给自己的团队搭一套统一 AI 编码规范的技术负责人。核心痛点其实很明确。你打开 Claude Code让它改一个 React 组件它不知道你们项目用的是 Zustand 还是 Redux不知道样式是 CSS Modules 还是 Tailwind不知道测试框架是 Vitest 还是 Jest。你每次都得重新说一遍说漏了它就瞎猜猜错了你还得回滚。SKILLS 这套机制的本质就是把上下文注入这件事从每次手动说变成按需自动挂载。v0.1.5这个版本号说明它还在早期功能不算完备但骨架已经能用了。它做的事情可以类比成给 AI 助手装了一套条件反射系统当任务类型匹配到某个 SKILL 的触发条件时对应的知识包和操作流程就会被激活。这跟传统的系统提示词最大的区别在于——系统提示词是全局常驻的SKILLS 是按场景动态加载的token 消耗更省干扰更少。2. 核心概念拆解SKILL 到底是什么2.1 SKILL 与普通提示词的本质区别很多人第一反应是这不就是提示词模板吗。不完全是。普通提示词模板是你复制粘贴一段话给 AISKILL 是一份带元数据的结构化文件它至少包含四个部分触发条件、知识内容、执行步骤、验证标准。触发条件决定了这个 SKILL 什么时候被激活。比如一个React 组件重构的 SKILL触发条件可能是用户提到 .tsx 文件且涉及组件拆分。知识内容是项目约定比如所有组件必须用函数式写法props 必须显式声明类型。执行步骤是操作流程比如先读原文件再列改动点确认后逐个替换。验证标准是改完后必须跑 tsc --noEmit 和对应单测。这四部分缺一不可。我见过有人只写了知识内容结果 AI 加载了 SKILL 但不知道该干什么反而更混乱。也见过只写步骤不写验证的改完代码一堆类型错误。2.2 Codex 与 Claude Code 的加载机制差异这两个工具虽然都支持 SKILLS 概念但加载机制不一样这点必须搞清楚否则你会遇到同一个 SKILL 在 Codex 里好用在 Claude Code 里不触发的情况。Codex 走的是配置文件驱动路线。你在项目根目录放一个配置文件里面声明 SKILL 的路径和触发规则Codex 启动时读取。它的优点是可控性强缺点是改配置要重启。Claude Code 走的是目录扫描 语义匹配路线它会在指定目录下扫描 SKILL 文件根据当前对话内容做语义匹配来决定加载哪个。优点是灵活缺点是匹配不准的时候你会很困惑为什么没触发。我的建议是两个工具共用同一套 SKILL 文件但分别维护各自的触发配置。SKILL 内容本身是纯 Markdown两边都能读差异只在触发层。2.3 目录结构设计一套能长期维护的 SKILLS 目录我实测下来这样组织最顺手.ai-skills/ skills/ react-refactor/ SKILL.md examples/ api-design/ SKILL.md db-migration/ SKILL.md config/ codex.yaml claude.json shared/ conventions.md每个 SKILL 一个目录目录名就是 SKILL 标识。SKILL.md是主文件examples/放参考案例。shared/conventions.md放全局通用约定各个 SKILL 可以引用它避免重复。这个结构的好处是新增 SKILL 不影响已有配置你只要在 config 里加一行路径就行。注意目录名不要用中文或空格Codex 在某些系统上解析路径时会出问题。我一开始用React重构做目录名结果触发一直失败改成react-refactor就好了。3. SKILL.md 的写法与关键字段3.1 文件头部元数据SKILL.md的开头必须有一段 YAML front matter这是两个工具都认的格式--- name: react-refactor version: 0.1.5 triggers: - 重构组件 - 拆分组件 - refactor component files: - **/*.tsx - **/*.jsx priority: 10 ---triggers是触发关键词中英文都写上因为你和 AI 对话时可能混用。files是文件匹配模式只有当操作涉及这些文件类型时 SKILL 才可能激活。priority是优先级数字越大越优先当多个 SKILL 同时匹配时用它决定谁先加载。这里有个坑triggers 不要写太宽泛的词。我一开始写了个组件结果每次提到组件库、组件文档都会触发重构 SKILL非常烦。后来改成重构组件、拆分组件这种带动作的词准确率立刻上来了。3.2 知识内容区元数据下面是正文用 Markdown 写。第一部分通常是项目约定## 项目约定 - 组件一律使用函数式写法禁止 class 组件 - props 类型用 interface 声明命名格式为 XxxProps - 样式优先使用 Tailwind 类名复杂样式抽到 styles/ 目录 - 状态管理统一用 Zustand禁止引入 Redux - 所有导出组件必须有 JSDoc 注释这些约定要写得具体到可执行。代码要规范这种话没用props 类型用 interface 且命名 XxxProps才有用。AI 需要的是明确的规则不是模糊的方向。3.3 执行步骤区步骤要写成有序列表每步都是一个可验证的动作## 执行步骤 1. 读取目标文件输出当前组件结构摘要 2. 识别可拆分的逻辑块列出拆分方案 3. 等待用户确认方案后再动手 4. 逐个创建新组件文件 5. 更新原文件的 import 和引用 6. 运行 tsc --noEmit 检查类型 7. 运行相关单测第 3 步等待用户确认很关键。我试过让 AI 直接改结果它拆出来的组件粒度完全不符合预期白改一遍。加上确认环节后返工率下降很多。3.4 验证标准区## 验证标准 - [ ] tsc --noEmit 无错误 - [ ] 相关单测全部通过 - [ ] 无未使用的 import - [ ] 新组件都有 JSDoc用 checkbox 格式写AI 会逐项检查。实测下来明确列出验证项比笼统说确保代码质量有效得多。4. 配置 Codex 加载 SKILLS4.1 配置文件位置与格式Codex 的配置默认在项目根目录的.codex/config.yaml也可以在用户目录放全局配置。项目级配置优先级更高。一个最小可用配置长这样skills: enabled: true paths: - .ai-skills/skills auto_load: true max_concurrent: 3 shared_context: - .ai-skills/shared/conventions.mdmax_concurrent控制同时加载的 SKILL 数量默认别超过 3加载太多会稀释 AI 的注意力反而降低效果。shared_context里的文件会被注入到每个 SKILL 的上下文里适合放全局约定。4.2 触发规则调优Codex 的触发是关键词匹配所以triggers的质量直接决定体验。我总结了一个调优方法先宽后窄逐步收敛。刚开始把可能相关的词都写上跑一周看日志里哪些触发是误报把误报的词删掉或改得更具体。Codex 会在.codex/logs/下记录触发日志格式是每行一个 JSON包含触发时间、匹配的 SKILL、匹配的关键词、当时的用户输入。这个日志是调优的金矿一定要看。4.3 常见配置错误错误现象原因解决SKILL 完全不触发paths 路径写错或用了绝对路径改成相对项目根目录的路径触发但内容为空SKILL.md 的 front matter 格式错误检查---是否成对YAML 缩进是否正确多个 SKILL 冲突priority 相同且触发词重叠给更专用的 SKILL 更高 priority加载后 AI 忽略内容max_concurrent 太大降到 2-3提示改完配置一定要重启 Codex 进程它不会热加载。我在这上面浪费过半小时一直以为配置写错了其实是没重启。5. 配置 Claude Code 加载 SKILLS5.1 目录约定与扫描机制Claude Code 的 SKILLS 加载靠目录扫描。默认扫描.claude/skills/目录每个子目录视为一个 SKILL。它不需要额外的配置文件但需要在项目根目录的.claude/settings.json里声明扫描路径{ skills: { paths: [.ai-skills/skills], match_mode: semantic, min_confidence: 0.6 } }match_mode设为semantic时走语义匹配设为keyword时走关键词匹配。语义匹配更智能但偶尔会误触发关键词匹配更准但需要你手动维护触发词。我的做法是日常用 semantic遇到误触发频繁的 SKILL 单独改成 keyword。5.2 语义匹配的调优技巧语义匹配的准确率取决于 SKILL.md 里描述文字的清晰度。有个技巧在 SKILL.md 开头加一段适用场景描述用自然语言说清楚什么时候该用这个 SKILL。Claude Code 会把这段描述和当前对话做语义比对。## 适用场景 当用户要求拆分一个过大的 React 组件、提取可复用逻辑、 或者提到组件职责过多需要重构时使用本 SKILL。 不适用于新建组件、修改样式、修复 bug 等场景。最后那句不适用于很重要它帮 AI 排除掉不该触发的场景。我加了这句之后误触发率明显下降。5.3 与 Codex 共用 SKILL 文件的注意事项两个工具共用 SKILL.md 时front matter 要写成两边都能解析的格式。Codex 认triggers字段Claude Code 认name和version所以这些字段都要有。files字段两边都认可以共用。有个细节Claude Code 对 front matter 的 YAML 解析比 Codex 严格不允许有 tab 缩进必须用空格。我一开始从别处复制了一段带 tab 的配置Codex 能读Claude Code 直接报错。统一用两个空格缩进就没问题。6. 一个完整的 SKILL 实战案例6.1 需求背景假设你有个 800 行的 React 组件Dashboard.tsx里面混了数据获取、状态管理、图表渲染、表格逻辑。你想把它拆成 4-5 个小组件。手动拆要半天用 SKILL 可以让 AI 按你的规范自动拆。6.2 编写 SKILL.md--- name: react-component-split version: 0.1.5 triggers: - 拆分组件 - 组件太大 - split component files: - **/*.tsx priority: 20 --- ## 适用场景 当用户要求拆分过大的 React 组件或提到组件职责过多、 单文件行数超过 300 行需要重构时使用。 ## 项目约定 - 函数式组件禁止 class - props 用 interface命名 XxxProps - 每个新组件单独一个文件放在同目录 - 数据获取逻辑抽到 hooks/ 目录 - 图表组件统一用 recharts ## 执行步骤 1. 读取目标文件统计行数和 import 数量 2. 按职责划分逻辑块输出拆分方案表格 3. 等待用户确认 4. 创建 hooks 文件如有数据逻辑 5. 创建子组件文件 6. 重写原文件只保留组合逻辑 7. 运行 tsc --noEmit 8. 运行相关单测 ## 验证标准 - [ ] 原文件行数降到 150 行以内 - [ ] 每个新组件职责单一 - [ ] 类型检查通过 - [ ] 单测通过6.3 实际执行记录我在一个真实项目里跑了一遍。原文件 812 行AI 读完输出了拆分方案数据获取抽成useDashboardDatahook图表部分拆成RevenueChart和UserChart表格拆成DataTable筛选器拆成FilterBar。方案表格里列了每个新组件的职责、预计行数、依赖关系。确认后 AI 开始创建文件。这里有个细节值得说它创建 hooks 文件时自动加了use前缀因为我在项目约定里写了数据获取逻辑抽到 hooks/ 目录它推断出命名规范。这说明约定写得越具体AI 的自主决策越靠谱。最终结果原文件降到 127 行新增 5 个文件类型检查一次通过单测全绿。整个过程大概 3 分钟手动做至少要 40 分钟。6.4 效果对比指标手动拆分SKILL 拆分耗时40 分钟3 分钟类型错误平均 2-3 个0命名一致性靠人记自动统一返工率较高低有确认环节7. 常见问题与排查技巧7.1 触发类问题问题SKILL 该触发时不触发。排查顺序先看日志确认有没有匹配到再看匹配到的关键词是不是你预期的。如果日志里根本没记录说明 paths 配置有问题。如果记录了但没加载说明 priority 被其他 SKILL 压过了。问题不该触发时乱触发。把宽泛的触发词删掉或者在适用场景里加排除条件。语义匹配模式下把min_confidence从 0.6 提到 0.7 也能减少误触发但会牺牲一些召回率。7.2 内容类问题问题AI 加载了 SKILL 但不按步骤执行。大概率是步骤写得太笼统。检查每步是不是都有明确的动作和产出物。分析代码这种步骤 AI 会跳过输出拆分方案表格就不会。步骤越具体执行越可靠。问题多个 SKILL 内容冲突。比如一个 SKILL 说用 Zustand另一个说用 Redux。这种情况要么合并成一个 SKILL要么在 shared/conventions.md 里统一声明各 SKILL 引用它。全局约定只写一处是避免冲突的根本方法。7.3 性能类问题问题加载 SKILL 后响应变慢。检查max_concurrent是不是设太大了。每个 SKILL 都会占用上下文窗口加载 5 个以上会明显拖慢响应。另外检查 SKILL.md 是不是写得太长单个 SKILL 超过 2000 字就该考虑拆分了。问题token 消耗异常高。用 Codex 的--verbose模式跑一次看它实际注入了多少内容。常见原因是 shared_context 里放了太大的文件或者某个 SKILL 的 examples 目录被整个加载了。examples 应该只在需要时手动引用不要自动加载。7.4 速查表现象最可能原因快速验证完全不触发paths 配置错误看日志有无记录触发但无效果front matter 格式错手动解析 YAML频繁误触发触发词太宽泛看日志匹配词响应变慢并发加载过多降 max_concurrent内容冲突全局约定分散检查 shared 引用8. 我踩过的几个坑和对应经验第一个坑是把 SKILL 写成了文档。我一开始写了个 3000 字的 SKILL把项目所有规范都塞进去结果 AI 加载后反而抓不住重点执行时经常漏步骤。后来拆成 5 个小 SKILL每个聚焦一个场景效果立刻好转。SKILL 不是文档是操作指令要短、要准、要可执行。第二个坑是忽略验证环节。早期我写的 SKILL 没有验证标准AI 改完代码就结束了我一看一堆类型错误。加上验证标准后AI 会主动跑检查有问题当场修。这个改动让返工率下降了一大半。第三个坑是两个工具用同一份配置。Codex 和 Claude Code 的配置格式不一样我一开始想偷懒共用结果两边都出问题。后来分开维护 configSKILL 内容共用就顺畅了。第四个坑是没有版本管理。SKILL 改来改去改坏了想回滚都找不到旧版本。现在我把.ai-skills/整个目录纳入 git 管理每次改动都有记录出问题能快速定位是哪次改动导致的。提示SKILL 的迭代节奏建议是小步快跑。每次只改一个点跑几天看效果有效就保留无效就回滚。一次性大改很难判断是哪个改动起了作用。9. 后续可以怎么扩展这套东西跑通之后能扩展的方向不少。我目前在做的是把 SKILL 和 CI 打通让 AI 在提交代码前自动跑一遍相关 SKILL 的验证标准不通过就拦住。这样能把很多低级错误挡在提交之前。另一个方向是团队共享 SKILL 库。把通用的 SKILL 抽出来放到一个独立仓库各项目通过 git submodule 引用。项目特有的 SKILL 放本地通用的走共享库。这样新项目接入时直接拉共享库就能用上一套成熟的规范。还有个想法是给 SKILL 加指标。记录每个 SKILL 的触发次数、执行成功率、平均耗时用数据来决定哪些 SKILL 值得保留、哪些该优化。这个需要改一点 Codex 的日志解析逻辑我还在摸索。最后分享一个小技巧SKILL 的触发词里加上你团队的黑话。比如你们内部管组件拆分叫切组件那就把切组件也加进 triggers。AI 不认识黑话但关键词匹配认加上之后触发准确率会高很多。这个细节文档里不会写但实际用起来很香。 
长河君 · 2026/10/10 7:45:39 · 阅读 1.2k AI编码助手技能编排实战：Codex与Claude Code的SKILLS配置指南
1. 这套工作流到底在解决什么问题第一次看到AI-Infra-Auto-Driven-SKILLS这个名字很多人会以为是某个新出的推理框架或者模型压缩工具。实际上它跟模型本身没太大关系它是一套给 Codex 和 Claude Code 这类命令行 AI 编码助手用的技能编排层。说白了就是把你平时反复手动敲的那些提示词、检查清单、代码规范、项目约定打包成一个个可复用的 SKILL让 AI 在合适的时机自动加载、自动执行。我用了大概两周时间把这套东西跑通中间踩了不少坑也总结出一些文档里不会写的经验。这篇文章就把整个思路、实现细节、实操步骤和排查技巧完整拆一遍适合两类人看一是已经在用 Codex 或 Claude Code 但觉得每次都要重复交代背景、效率上不去的开发者二是想给自己的团队搭一套统一 AI 编码规范的技术负责人。核心痛点其实很明确。你打开 Claude Code让它改一个 React 组件它不知道你们项目用的是 Zustand 还是 Redux不知道样式是 CSS Modules 还是 Tailwind不知道测试框架是 Vitest 还是 Jest。你每次都得重新说一遍说漏了它就瞎猜猜错了你还得回滚。SKILLS 这套机制的本质就是把上下文注入这件事从每次手动说变成按需自动挂载。v0.1.5这个版本号说明它还在早期功能不算完备但骨架已经能用了。它做的事情可以类比成给 AI 助手装了一套条件反射系统当任务类型匹配到某个 SKILL 的触发条件时对应的知识包和操作流程就会被激活。这跟传统的系统提示词最大的区别在于——系统提示词是全局常驻的SKILLS 是按场景动态加载的token 消耗更省干扰更少。2. 核心概念拆解SKILL 到底是什么2.1 SKILL 与普通提示词的本质区别很多人第一反应是这不就是提示词模板吗。不完全是。普通提示词模板是你复制粘贴一段话给 AISKILL 是一份带元数据的结构化文件它至少包含四个部分触发条件、知识内容、执行步骤、验证标准。触发条件决定了这个 SKILL 什么时候被激活。比如一个React 组件重构的 SKILL触发条件可能是用户提到 .tsx 文件且涉及组件拆分。知识内容是项目约定比如所有组件必须用函数式写法props 必须显式声明类型。执行步骤是操作流程比如先读原文件再列改动点确认后逐个替换。验证标准是改完后必须跑 tsc --noEmit 和对应单测。这四部分缺一不可。我见过有人只写了知识内容结果 AI 加载了 SKILL 但不知道该干什么反而更混乱。也见过只写步骤不写验证的改完代码一堆类型错误。2.2 Codex 与 Claude Code 的加载机制差异这两个工具虽然都支持 SKILLS 概念但加载机制不一样这点必须搞清楚否则你会遇到同一个 SKILL 在 Codex 里好用在 Claude Code 里不触发的情况。Codex 走的是配置文件驱动路线。你在项目根目录放一个配置文件里面声明 SKILL 的路径和触发规则Codex 启动时读取。它的优点是可控性强缺点是改配置要重启。Claude Code 走的是目录扫描 语义匹配路线它会在指定目录下扫描 SKILL 文件根据当前对话内容做语义匹配来决定加载哪个。优点是灵活缺点是匹配不准的时候你会很困惑为什么没触发。我的建议是两个工具共用同一套 SKILL 文件但分别维护各自的触发配置。SKILL 内容本身是纯 Markdown两边都能读差异只在触发层。2.3 目录结构设计一套能长期维护的 SKILLS 目录我实测下来这样组织最顺手.ai-skills/ skills/ react-refactor/ SKILL.md examples/ api-design/ SKILL.md db-migration/ SKILL.md config/ codex.yaml claude.json shared/ conventions.md每个 SKILL 一个目录目录名就是 SKILL 标识。SKILL.md是主文件examples/放参考案例。shared/conventions.md放全局通用约定各个 SKILL 可以引用它避免重复。这个结构的好处是新增 SKILL 不影响已有配置你只要在 config 里加一行路径就行。注意目录名不要用中文或空格Codex 在某些系统上解析路径时会出问题。我一开始用React重构做目录名结果触发一直失败改成react-refactor就好了。3. SKILL.md 的写法与关键字段3.1 文件头部元数据SKILL.md的开头必须有一段 YAML front matter这是两个工具都认的格式--- name: react-refactor version: 0.1.5 triggers: - 重构组件 - 拆分组件 - refactor component files: - **/*.tsx - **/*.jsx priority: 10 ---triggers是触发关键词中英文都写上因为你和 AI 对话时可能混用。files是文件匹配模式只有当操作涉及这些文件类型时 SKILL 才可能激活。priority是优先级数字越大越优先当多个 SKILL 同时匹配时用它决定谁先加载。这里有个坑triggers 不要写太宽泛的词。我一开始写了个组件结果每次提到组件库、组件文档都会触发重构 SKILL非常烦。后来改成重构组件、拆分组件这种带动作的词准确率立刻上来了。3.2 知识内容区元数据下面是正文用 Markdown 写。第一部分通常是项目约定## 项目约定 - 组件一律使用函数式写法禁止 class 组件 - props 类型用 interface 声明命名格式为 XxxProps - 样式优先使用 Tailwind 类名复杂样式抽到 styles/ 目录 - 状态管理统一用 Zustand禁止引入 Redux - 所有导出组件必须有 JSDoc 注释这些约定要写得具体到可执行。代码要规范这种话没用props 类型用 interface 且命名 XxxProps才有用。AI 需要的是明确的规则不是模糊的方向。3.3 执行步骤区步骤要写成有序列表每步都是一个可验证的动作## 执行步骤 1. 读取目标文件输出当前组件结构摘要 2. 识别可拆分的逻辑块列出拆分方案 3. 等待用户确认方案后再动手 4. 逐个创建新组件文件 5. 更新原文件的 import 和引用 6. 运行 tsc --noEmit 检查类型 7. 运行相关单测第 3 步等待用户确认很关键。我试过让 AI 直接改结果它拆出来的组件粒度完全不符合预期白改一遍。加上确认环节后返工率下降很多。3.4 验证标准区## 验证标准 - [ ] tsc --noEmit 无错误 - [ ] 相关单测全部通过 - [ ] 无未使用的 import - [ ] 新组件都有 JSDoc用 checkbox 格式写AI 会逐项检查。实测下来明确列出验证项比笼统说确保代码质量有效得多。4. 配置 Codex 加载 SKILLS4.1 配置文件位置与格式Codex 的配置默认在项目根目录的.codex/config.yaml也可以在用户目录放全局配置。项目级配置优先级更高。一个最小可用配置长这样skills: enabled: true paths: - .ai-skills/skills auto_load: true max_concurrent: 3 shared_context: - .ai-skills/shared/conventions.mdmax_concurrent控制同时加载的 SKILL 数量默认别超过 3加载太多会稀释 AI 的注意力反而降低效果。shared_context里的文件会被注入到每个 SKILL 的上下文里适合放全局约定。4.2 触发规则调优Codex 的触发是关键词匹配所以triggers的质量直接决定体验。我总结了一个调优方法先宽后窄逐步收敛。刚开始把可能相关的词都写上跑一周看日志里哪些触发是误报把误报的词删掉或改得更具体。Codex 会在.codex/logs/下记录触发日志格式是每行一个 JSON包含触发时间、匹配的 SKILL、匹配的关键词、当时的用户输入。这个日志是调优的金矿一定要看。4.3 常见配置错误错误现象原因解决SKILL 完全不触发paths 路径写错或用了绝对路径改成相对项目根目录的路径触发但内容为空SKILL.md 的 front matter 格式错误检查---是否成对YAML 缩进是否正确多个 SKILL 冲突priority 相同且触发词重叠给更专用的 SKILL 更高 priority加载后 AI 忽略内容max_concurrent 太大降到 2-3提示改完配置一定要重启 Codex 进程它不会热加载。我在这上面浪费过半小时一直以为配置写错了其实是没重启。5. 配置 Claude Code 加载 SKILLS5.1 目录约定与扫描机制Claude Code 的 SKILLS 加载靠目录扫描。默认扫描.claude/skills/目录每个子目录视为一个 SKILL。它不需要额外的配置文件但需要在项目根目录的.claude/settings.json里声明扫描路径{ skills: { paths: [.ai-skills/skills], match_mode: semantic, min_confidence: 0.6 } }match_mode设为semantic时走语义匹配设为keyword时走关键词匹配。语义匹配更智能但偶尔会误触发关键词匹配更准但需要你手动维护触发词。我的做法是日常用 semantic遇到误触发频繁的 SKILL 单独改成 keyword。5.2 语义匹配的调优技巧语义匹配的准确率取决于 SKILL.md 里描述文字的清晰度。有个技巧在 SKILL.md 开头加一段适用场景描述用自然语言说清楚什么时候该用这个 SKILL。Claude Code 会把这段描述和当前对话做语义比对。## 适用场景 当用户要求拆分一个过大的 React 组件、提取可复用逻辑、 或者提到组件职责过多需要重构时使用本 SKILL。 不适用于新建组件、修改样式、修复 bug 等场景。最后那句不适用于很重要它帮 AI 排除掉不该触发的场景。我加了这句之后误触发率明显下降。5.3 与 Codex 共用 SKILL 文件的注意事项两个工具共用 SKILL.md 时front matter 要写成两边都能解析的格式。Codex 认triggers字段Claude Code 认name和version所以这些字段都要有。files字段两边都认可以共用。有个细节Claude Code 对 front matter 的 YAML 解析比 Codex 严格不允许有 tab 缩进必须用空格。我一开始从别处复制了一段带 tab 的配置Codex 能读Claude Code 直接报错。统一用两个空格缩进就没问题。6. 一个完整的 SKILL 实战案例6.1 需求背景假设你有个 800 行的 React 组件Dashboard.tsx里面混了数据获取、状态管理、图表渲染、表格逻辑。你想把它拆成 4-5 个小组件。手动拆要半天用 SKILL 可以让 AI 按你的规范自动拆。6.2 编写 SKILL.md--- name: react-component-split version: 0.1.5 triggers: - 拆分组件 - 组件太大 - split component files: - **/*.tsx priority: 20 --- ## 适用场景 当用户要求拆分过大的 React 组件或提到组件职责过多、 单文件行数超过 300 行需要重构时使用。 ## 项目约定 - 函数式组件禁止 class - props 用 interface命名 XxxProps - 每个新组件单独一个文件放在同目录 - 数据获取逻辑抽到 hooks/ 目录 - 图表组件统一用 recharts ## 执行步骤 1. 读取目标文件统计行数和 import 数量 2. 按职责划分逻辑块输出拆分方案表格 3. 等待用户确认 4. 创建 hooks 文件如有数据逻辑 5. 创建子组件文件 6. 重写原文件只保留组合逻辑 7. 运行 tsc --noEmit 8. 运行相关单测 ## 验证标准 - [ ] 原文件行数降到 150 行以内 - [ ] 每个新组件职责单一 - [ ] 类型检查通过 - [ ] 单测通过6.3 实际执行记录我在一个真实项目里跑了一遍。原文件 812 行AI 读完输出了拆分方案数据获取抽成useDashboardDatahook图表部分拆成RevenueChart和UserChart表格拆成DataTable筛选器拆成FilterBar。方案表格里列了每个新组件的职责、预计行数、依赖关系。确认后 AI 开始创建文件。这里有个细节值得说它创建 hooks 文件时自动加了use前缀因为我在项目约定里写了数据获取逻辑抽到 hooks/ 目录它推断出命名规范。这说明约定写得越具体AI 的自主决策越靠谱。最终结果原文件降到 127 行新增 5 个文件类型检查一次通过单测全绿。整个过程大概 3 分钟手动做至少要 40 分钟。6.4 效果对比指标手动拆分SKILL 拆分耗时40 分钟3 分钟类型错误平均 2-3 个0命名一致性靠人记自动统一返工率较高低有确认环节7. 常见问题与排查技巧7.1 触发类问题问题SKILL 该触发时不触发。排查顺序先看日志确认有没有匹配到再看匹配到的关键词是不是你预期的。如果日志里根本没记录说明 paths 配置有问题。如果记录了但没加载说明 priority 被其他 SKILL 压过了。问题不该触发时乱触发。把宽泛的触发词删掉或者在适用场景里加排除条件。语义匹配模式下把min_confidence从 0.6 提到 0.7 也能减少误触发但会牺牲一些召回率。7.2 内容类问题问题AI 加载了 SKILL 但不按步骤执行。大概率是步骤写得太笼统。检查每步是不是都有明确的动作和产出物。分析代码这种步骤 AI 会跳过输出拆分方案表格就不会。步骤越具体执行越可靠。问题多个 SKILL 内容冲突。比如一个 SKILL 说用 Zustand另一个说用 Redux。这种情况要么合并成一个 SKILL要么在 shared/conventions.md 里统一声明各 SKILL 引用它。全局约定只写一处是避免冲突的根本方法。7.3 性能类问题问题加载 SKILL 后响应变慢。检查max_concurrent是不是设太大了。每个 SKILL 都会占用上下文窗口加载 5 个以上会明显拖慢响应。另外检查 SKILL.md 是不是写得太长单个 SKILL 超过 2000 字就该考虑拆分了。问题token 消耗异常高。用 Codex 的--verbose模式跑一次看它实际注入了多少内容。常见原因是 shared_context 里放了太大的文件或者某个 SKILL 的 examples 目录被整个加载了。examples 应该只在需要时手动引用不要自动加载。7.4 速查表现象最可能原因快速验证完全不触发paths 配置错误看日志有无记录触发但无效果front matter 格式错手动解析 YAML频繁误触发触发词太宽泛看日志匹配词响应变慢并发加载过多降 max_concurrent内容冲突全局约定分散检查 shared 引用8. 我踩过的几个坑和对应经验第一个坑是把 SKILL 写成了文档。我一开始写了个 3000 字的 SKILL把项目所有规范都塞进去结果 AI 加载后反而抓不住重点执行时经常漏步骤。后来拆成 5 个小 SKILL每个聚焦一个场景效果立刻好转。SKILL 不是文档是操作指令要短、要准、要可执行。第二个坑是忽略验证环节。早期我写的 SKILL 没有验证标准AI 改完代码就结束了我一看一堆类型错误。加上验证标准后AI 会主动跑检查有问题当场修。这个改动让返工率下降了一大半。第三个坑是两个工具用同一份配置。Codex 和 Claude Code 的配置格式不一样我一开始想偷懒共用结果两边都出问题。后来分开维护 configSKILL 内容共用就顺畅了。第四个坑是没有版本管理。SKILL 改来改去改坏了想回滚都找不到旧版本。现在我把.ai-skills/整个目录纳入 git 管理每次改动都有记录出问题能快速定位是哪次改动导致的。提示SKILL 的迭代节奏建议是小步快跑。每次只改一个点跑几天看效果有效就保留无效就回滚。一次性大改很难判断是哪个改动起了作用。9. 后续可以怎么扩展这套东西跑通之后能扩展的方向不少。我目前在做的是把 SKILL 和 CI 打通让 AI 在提交代码前自动跑一遍相关 SKILL 的验证标准不通过就拦住。这样能把很多低级错误挡在提交之前。另一个方向是团队共享 SKILL 库。把通用的 SKILL 抽出来放到一个独立仓库各项目通过 git submodule 引用。项目特有的 SKILL 放本地通用的走共享库。这样新项目接入时直接拉共享库就能用上一套成熟的规范。还有个想法是给 SKILL 加指标。记录每个 SKILL 的触发次数、执行成功率、平均耗时用数据来决定哪些 SKILL 值得保留、哪些该优化。这个需要改一点 Codex 的日志解析逻辑我还在摸索。最后分享一个小技巧SKILL 的触发词里加上你团队的黑话。比如你们内部管组件拆分叫切组件那就把切组件也加进 triggers。AI 不认识黑话但关键词匹配认加上之后触发准确率会高很多。这个细节文档里不会写但实际用起来很香。