如果你同时用 Claude Code、Codex 这类命令行 AI 编程工具大概率遇到过这个尴尬在 Claude Code 里精心调好的 Skills换到 Codex 又得重新配一遍或者团队里同一个项目维护两套 skills改了一处忘了另一处模型行为立刻漂移。这个方案解决的就是这个问题——把 Skills 做成一份、多处引用让 Claude Code、Codex 共享同一套技能库改一次全生效。无论你是个人开发者还是小团队里负责 AI 工程化的人这套统一管理思路都能直接落地不需要额外引入重型平台几个命令加一个 git 仓库就能跑起来。前后折腾了大概两周我在自己几个项目里来回切换、踩了不少坑最后沉淀出了一套比较顺手的结构。下面我把完整的设计思路、目录结构、配置步骤和排障记录都写出来希望对正在被多 Agent 技能管理折磨的人有点帮助。1. 先说清楚为什么一套 Skills 要拆给多个 Agent 用1.1 多 Agent 切换的真实痛点我手头同时维护几个项目有些是老项目习惯用 Claude Code 跑有些是偏轻量的原型用 Codex 更快。按理说代码生成、前端开发、代码审查、文档生成这类 Skills两边都要用但它们默认读取的目录完全不同。早期我就是最简单的办法把同一个 skill 复制到 Claude Code 的 skills 目录再复制一份到 Codex 的 skills 目录。第一次配完确实能用可问题出在迭代上。比如我做了一个前端开发的 skills里面收集了不少组件规范今天改了命名规则明天加了新的代码风格约束结果只改了 Claude Code 那份Codex 那边还是旧版本生成出来的代码风格立刻分叉。更难受的是同一个 skill 在两个工具里会被分别触发但触发条件和行为不一致。你在 Claude Code 里用得好好的切到 Codex 突然不生效排查半天发现是复制的时候漏了一个资源文件。这种问题不致命但特别消磨耐心。1.2 Skills 本质上是个什么“包”要统一管理得先搞清楚 Skills 到底是什么。简单说Skills 是一个带固定结构的目录目录里必须有一个SKILL.md文件里面用 YAML frontmatter 写name和description然后正文是具体的操作指导。除了SKILL.md目录下还可以放脚本、参考文档、模板文件等资源。模型运行时会根据当前对话内容去匹配各个 skill 的description觉得“这个场景符合”就把SKILL.md加载进上下文按里面的步骤执行。可以把它理解成“浏览器插件 使用说明书”插件本身是脚本和资源说明书告诉模型什么时候该用、怎么用。这种设计天然适合共享因为本质就是一个文件夹工具只是按约定路径去找它。既然是这样我们完全可以通过路径映射让多个工具指向同一个文件夹。1.3 复制三份为什么会把项目搞崩也许有人会说不就是多复制一份吗有那么严重吗我的真实体会是复制带来的问题不是即刻爆发而是累积的。第一内容漂移。你今天改了这个没改那个几天后两边行为就不一致了而且你根本记不清哪个是最新的。第二资源遗漏。SKILL.md 里引用了一个scripts/validate.py复制的时候很容易只复制了 md 文件脚本没带过去模型按步骤执行到某一步就会报错。第三团队协作无解。两个人同时改 A 工具里的 skill改完怎么合并谁有权限改全乱套。所以我的结论是Skills 必须做单一来源其他 Agent 全部引用这一份而不是各自持有副本。2. 统一管理方案的整体设计2.1 先定路径收敛策略每个工具都有自己的默认 skills 目录我们不去跟它的默认机制对抗而是把默认目录做成“跳板”。现在主流工具的目录大致是这样工具用户级默认路径项目级默认路径Claude Code~/.claude/skills.claude/skillsCodex~/.codex/skills部分版本.codex/skills视版本而定如果两个工具都支持读取自定义路径优先级最高的方案是直接在 config 里指向统一目录。如果某个工具版本不支持就用符号链接把它的默认目录映射到统一目录。这套思路的核心是不管工具内部怎么查找最终都落到同一个物理目录。注意不同版本的工具对 skills 路径的支持有差异。建议先跑一遍最新的安装包确认有没有官方配置项再去决定用哪种方式。2.2 用符号链接把两套目录映射到同一仓库我选定的结构是一个独立的 git 仓库专门放 skills各工具的配置目录里放符号链接指向这个仓库下的对应子目录。skills-repo/ ├── frontend-dev/ │ ├── SKILL.md │ ├── scripts/ │ └── templates/ ├── code-review/ │ ├── SKILL.md │ └── rules/ ├── docs-generator/ │ ├── SKILL.md │ └── templates/ └── README.md然后在 Claude Code 和 Codex 的目录里分别建链接ln -s ~/workspace/skills-repo/frontend-dev ~/.claude/skills/frontend-dev ln -s ~/workspace/skills-repo/frontend-dev ~/.codex/skills/frontend-dev这样两边读到的都是同一个frontend-dev目录改一处两边同时生效。2.3 为什么不用复制、不用同步脚本我试过复制方案也尝试写 rsync 同步脚本最后都放弃了。复制的问题刚才说过漂移是必然的。同步脚本看似自动但有几个致命问题一是需要额外守护进程或 cron环境一变就忘记二是冲突处理麻烦两边各自改了同一个文件同步时到底覆盖哪边三是不够透明脚本跑没跑、什么时候跑的全靠自觉。符号链接最大的好处是“删除了同步概念”。你只有一份实体文件其他全部是引用天然避免冲突。git 更新也简单git pull完所有工具下次启动自动看到新版本。这在团队协作里价值更大因为每个人本地拉同一个仓库行为完全一致。3. 实操让 Claude Code 和 Codex 读取同一套 skills3.1 建立统一 skills 仓库我建议先建一个独立的仓库不要和你项目代码混在一起。原因很简单skills 的使用范围往往跨项目前端开发规范可能适用于 A 项目也适用于 B 项目单独仓库更容易管理和复用。mkdir skills-repo cd skills-repo git init mkdir frontend-dev然后创建第一个 skill 的 SKILL.md--- name: frontend-dev description: 用于前端页面开发包括组件结构、样式规范、交互逻辑等。当用户提到写页面、调样式、组件拆分时使用。 --- # 前端开发技能 ...这里有个细节目录名和name字段保持一致后面排查会省很多事。目录用短横线命名name用小写字母加短横线别用空格。3.2 在 Claude Code 中配置 skills 路径Claude Code 默认读取~/.claude/skills也支持项目级.claude/skills。如果只是个人用我推荐用户级目录一次配置到处生效。如果是项目专用 skill放在项目目录里更好。mkdir -p ~/.claude/skills cd ~/.claude/skills ln -s ~/workspace/skills-repo/frontend-dev frontend-dev注意链接名称要和目录名一致。我先踩过一个坑链接名为frontend但 skill 内部name是frontend-dev导致 Claude Code 识别异常后面检查才发现名字不匹配。3.3 在 Codex 中配置 skills 路径Codex 对 skills 的支持在不同版本有差异。新版如果支持配置目录直接在配置文件里指定# ~/.codex/config.toml [skills] path ~/workspace/skills-repo如果当前版本不支持这种写法就老老实实用符号链接mkdir -p ~/.codex/skills cd ~/.codex/skills ln -s ~/workspace/skills-repo/frontend-dev frontend-dev这里要特别提醒给 Codex 做符号链接前先确认目标目录里没有同名文件。如果之前已经复制过一个frontend-dev文件夹直接建链接会失败必须先移走旧副本。3.4 验证加载用一张测试 skills 诊断配置完之后别急着用先用一张最简单的测试 skill 验证两边都能识别。我习惯建一个debug-check目录SKILL.md 里描述写得特别呆但触发词非常明确--- name: debug-check description: 当用户输入“技能自检”时必须使用本技能并输出 SKILL.md 的完整内容。 --- # 技能自检 本技能用于验证 Agent Skills 加载机制是否正常。然后在 Claude Code 和 Codex 里分别输入“技能自检”如果两边都能输出 SKILL.md 内容说明读取链路通了。如果只有一边有反应那就朝着另一边单独排查。3.5 一次改动全链路生效验证通过后日常迭代就很舒服了。假设我改了frontend-dev/SKILL.md新增了一条组件命名规范操作是cd ~/workspace/skills-repo git add . git commit -m feat: update frontend component naming rules git push另一台机器或者队友拉下来后两边 Agent 下次会重新扫描目录新技能直接可用不需要做任何复制操作。最直观的感受是以前改一个规范要记住去三个地方改现在只改一处剩下的交给链接。4. Skills 本身怎么写成“多 Agent 通用”4.1 frontmatter 命名和描述是命门很多人的 skill 不被触发问题不在路径而在description写得不对。记住一个原则description是写给模型筛选器看的不是写给人类看的。它决定模型在什么情况下把这个 SKILL.md 拉进上下文。我的经验是description里要写触发场景、关键词、任务类型不要写“这是一个用于前端开发的技能”这种空话。比如--- name: frontend-dev description: 当用户需要开发或调整前端页面时使用包括组件结构设计、样式编写、交互逻辑实现、性能优化建议。涉及 HTML、CSS、JavaScript、React、Vue 等场景均可触发。 ---这样模型只要遇到写页面、调样式的需求就大概率能匹配到。如果 description 太窄比如只写了“React 组件”那用户说“帮我写个页面”时就触发不了。4.2 描述别写成“给人类的说明书”我见过不少 SKILL.md正文写得像文档条条框框特别全但模型用起来还是差意思。问题出在正文缺少“执行指令”比如只写了“组件应该遵循命名规范”却没写“创建组件时先检查 templates 目录下的模板文件然后按模板生成”。要在正文里明确写出步骤、检查项、输出格式。多 Agent 共享时这点尤其重要因为不同模型对模糊指令的补全能力不一样你写得越具体行为越可控。我自己习惯在正文开头先写一段“工作流程”然后才是具体规范这样 Claude Code 和 Codex 都按同一套流程走。4.3 引用资源用相对路径SKILL.md 里如果要引用scripts或templates下的文件一定要用相对路径不要用绝对路径。你本地是/Users/me/workspace/skills-repo/frontend-dev/scripts/deploy.sh队友那边可能是/home/other/skills-repo/...写死绝对路径链接共享就直接失效。相对路径写法参考资源 - scripts/validate-component.js - templates/page-template.tsx另外脚本文件记得加执行权限。有些系统下Codex 调用脚本时如果权限不对会直接失败。统一管理之后这个问题更容易暴露因为之前各工具可能在各自目录里格式化了权限。4.4 跨工具测试的清单我现在每写一个新 skill至少过一遍这个清单目录名和 name 一致。description 包含至少三个触发场景词。正文步骤足够具体没有“等等”“等等再说”这种模糊词。引用文件用的是相对路径。脚本可执行依赖已注明。在 Claude Code 里触发一次在 Codex 里触发一次。故意修改一处内容确认另一工具下次加载时能看到变化。这套清单看起来繁琐但能省掉后续大量排查时间。尤其是最后一条很多人验证一次能用就完事了结果改完没生效又怀疑人生。5. 常见问题与排查技巧实录5.1 skills 没被触发这是最频发的问题。原因通常是 description 写得太窄或者太宽。太窄导致模型不觉得当前任务匹配太宽导致模型把它当成普通上下文塞进去但没执行正文步骤。排查思路是先看日志或者直接用测试 skill 验证。如果测试 skill 能触发说明路径没问题问题出在具体 skill 的 description 上。我会先把 description 里的触发词列出来对照真实任务描述看有没有交集。没有交集就补词有交集还触发不了再看是不是被打到了别的 skill 上。5.2 符号链接在某些环境下失效符号链接在 macOS、Linux 下很顺手但 Windows 下经常遇到权限问题或者工具内部读文件时不处理 symlink。还有少数工具在“加载资源文件列表”时用的是递归遍历某些版本不跟随链接导致 SKILL.md 能读到但脚本读不到。如果符号链接失效我的兜底方案是用 Windows 的目录联接junction或者直接做一个“拉取脚本”在每次启动 Agent 前把仓库内容同步到目录里。虽然这又回到同步脚本的老路但至少只做单向覆盖比两边手改强。5.3 frontmatter 解析失败缩进和编码SKILL.md 的 YAML frontmatter 解析失败通常表现是工具直接提示找不到 skill或者加载了但 name 是空。常见原因有两个一是缩进用了 Tab二是文件保存成了带 BOM 的 UTF-8。这两个问题在跨平台协作时特别容易冒出来Windows 编辑器默认会加 BOMGitHub 合并时也可能引入奇怪字符。我一般在仓库根目录放一个.editorconfig强制 YAML 文件用空格缩进、UTF-8 无 BOM。另外本地检查时用 Python 快速验证一下python -c import yaml,sys; yaml.safe_load(open(sys.argv[1], encodingutf-8-sig)) SKILL.md能稳定 parse 再提交。5.4 遇到 endpoint /responses 的报错怎么定位用 Codex 时偶尔会看到类似endpoint /responses相关的报错或者切换提供方后提示本地服务端点处理失败。多数情况下这不是 skills 配置问题而是工具本身的服务端点配置和当前提供方不一致或者本地有环境变量残留。我的处理方式是先确认工具当前的 provider 配置再看环境变量里有没有旧的服务地址把它清掉再重试。如果还不行就检查是不是本地某个中间服务没有启动或者说缓存了旧配置。这种情况跟 skills 无关但因为它发生在请求阶段容易被误以为是技能问题所以排查时要先把链路拆开。5.5 多人协作时的分支和 review一个人搞 skills 很容易团队协作就会遇到“谁改了命名规范为什么改了”这种问题。我的做法是 skills 仓库单独拉分支每个改动都走 PR甚至要求改动描述里写上“影响的 Agent 范围”。这样做除了有记录还有一个好处review 时能强制检查 description 是否与真实任务对齐。有时候写的人觉得描述很清楚了实际别人理解完全跑偏。PR 里专门加一条 checklist让 review 的人从模型视角读一遍 description能有效减少无效 skill。6. 写在最后一点个人体会折腾这套方案的过程中我最深刻的体会是Skills 本身不是越大越好能被反复触发、稳定执行的技能才值得沉淀。统一管理的意义不止是少复制几份文件而是让你开始认真地考虑“这个技能到底该不该存在”。以前复制一份不心疼冗余也无所谓现在所有 Agent 指向同一份你就会更在意它的质量、描述和边界。另外我在实际使用中发现做得好的 skill 往往不是一次性写出来的而是在真实项目里反复磨出来的。先写一个粗糙版本遇到没触发的情况就改描述遇到行为不对就补步骤慢慢变成顺手的状态。这套统一管理的模式恰好让这个过程变得可迭代、可回溯。如果你也在多 Agent 间切来切去建议从这个周末开始建一个 skills 仓库把第一条链接打通后面会越用越顺。