尧图网站建设 
我记得第一次在 Claude Code 里折腾完一套 Skills兴冲冲切到 Codex 准备复用结果发现两边的加载机制完全不在一个频道上。后来查了一圈文档才明白Claude Code 认的是个人目录下的 SKILL.mdCodex 认的是 AGENTS.md 和结构化说明文件两边既不共用一套目录也不共用一套格式。这不只是多复制一份文件的问题——同一套技能在两边逐渐长出两个版本修了左边忘右边很快就是一笔糊涂账。这篇内容想聊的是一套多 Agent 共享的 Skills 统一管理方案。目标很明确同一个技能仓库Claude Code 和 Codex 都能用改动一处两边同时生效不再各自维护。文章里会讲清两套工具的加载机制差异、共享目录的规划方式、软链接与配置文件的落地做法以及我在实际操作中遇到的几个坑。适合正在同时使用多个编程 Agent、又不想被技能配置反复折磨的开发者。1. 为什么多 Agent 共用一个 Skills 目录比各搞各的更靠谱1.1 先搞清痛点你到底在重复维护什么先说个常见场景。你写了一套前端开发 Skills里面包括组件生成规范、Page 结构约定、样式方案选择逻辑一共三个技能文件。在 Claude Code 里用顺手了切到 Codex 发现它根本不读这个目录于是你照着 Codex 的规则又整理了一份。两边语法不一样描述一个长一个短用着用着你会发现 Claude Code 那边的技能更新了组件规范Codex 那边还是老一套。这个问题的本质不是“没复制文件”而是“同一份知识体被拆成了两套独立维护”。技能不是一次性写死的配置——它会随着项目规范、团队约定、你个人的工程习惯不断迭代。只要有两份副本存在同步就是永无止境的事。另一个更隐蔽的问题是上下文污染。很多人的做法是把 Claude Code 的 skills 目录整个拷给 Codex结果 Codex 加载了一大堆为 Claude Code 专属语法设计的说明文件。轻则浪费上下文窗口重则产生互相矛盾的指令Agent 的回复风格飘忽不定。1.2 方案选型统一仓库加软链接而不是复制粘贴我最终采用的方案是三层结构一个统一技能仓库作为唯一事实来源两个 Agent 的加载目录通过软链接指向仓库内部再加上一个按 Agent 区分的薄适配层。统一仓库解决的是版本一致性问题所有技能文件只存在一份改动直接对所有 Agent 生效。软链接解决的是路径识别问题Claude Code 有它固定的技能搜索目录Codex 也有它固定的说明文件目录两边不强行改变搜索逻辑而是把相同的内容“映射”过去。适配层解决的是语法差异问题两边真正读取的顶层文件可以不同但它们指向的内容是共享的。提示这套思路不光适用于 Claude Code 和 CodexOpenCode、Cline 这类支持自定义指令目录的工具都能套用。核心原则是“一份源、多处引用”永远不要用复制粘贴来管理技能文件。1.3 目录规划先搭一个不依赖厂商的中间层我建议把技能仓库放在~/.ai-skills/下不挂在任何一家工具的配置目录里。这个目录的好处是独立、干净后续就算某家 Agent 改了配置规范也不会牵连到你的技能源文件。目录内部按“技能包”组织每个技能包就是一个子目录~/.ai-skills/ ├── skills/ │ ├── frontend-dev/ │ │ ├── SKILL.md │ │ └── references/ │ │ ├── component-guide.md │ │ └── page-structure.md │ ├── academic-writing/ │ │ ├── SKILL.md │ │ └── references/ │ └── math-modeling/ │ ├── SKILL.md │ └── references/每个技能包内部用 SKILL.md 作为统一入口文件references 目录存放支持材料。这个结构参考了目前主流 Agent 工具的技能描述规范但刻意不写死某一家语法的专属字段为后面的多 Agent 适配留出余地。2. 核心细节解析Claude Code 与 Codex 的加载机制到底差在哪2.1 Claude Code 侧frontmatter 加 SKILL.md 的加载逻辑Claude Code 的技能加载走的是个人目录扫描机制。它会在~/.claude/skills/部分环境可能是项目级.claude/skills/下扫描所有子目录读取每个子目录里的 SKILL.md 文件解析文件头部的 YAML frontmatter把名称、描述、依赖项等元数据注册进技能列表。当你在对话中输入#时就会弹出已加载的技能列表选中后对应的完整指令和参考资料才会进入上下文。这个机制有个关键特点技能目录的名字和 SKILL.md 里的 name 字段是被分别对待的。目录名影响的是文件系统的组织方式name 字段才是 Agent 真正用来识别和引用技能的名称。我见过有人只改目录名不改 name结果 Agent 识别出的技能名还是旧的排查了半天。SKILL.md 的 frontmatter 至少要包含name和descriptiondescription 写得越精确Agent 在相关场景下主动调用技能的概率就越高。正文部分用 Markdown 写清楚技能的执行步骤、输入输出约定、质量标准和禁止事项。Claude Code 对正文的格式没有特别严格的约束它会把整个文件作为指令注入上下文但注入的内容不宜过长否则会占用宝贵的上下文空间。2.2 Codex 侧AGENTS.md 与说明文件体系的组织方式Codex 和 Claude Code 的策略不太一样。它更依赖 AGENTS.md 这种渐进式披露的结构化说明文件。Codex 在会话开始时读入的是入口级 AGENTS.md里面不会写满大段操作细节而是用路径引用方式告诉模型“每个领域的具体规范在哪个文件里”模型在处理具体任务时再去读取对应文件。这意味着 Codex 侧的“技能”本质上不是一个被注册的插件而是一个被组织过的知识空间。你想让 Claude Code 的一个技能包在 Codex 里可用不能直接丢一个 SKILL.md 进去而是要在 Codex 能读到的说明文件里写明这个技能包的位置、用途和读取路径。实际落地时我会在~/.codex/下维护一个统一的 AGENTS.md把~/.ai-skills/skills/下的技能包逐个登记进去。登记项不用太长说清楚技能名称、适用场景、入口文件路径即可细节让 Codex 在需要时自己去读。2.3 格式差异的适配思路一份内容两张说明书整理完两边机制你可能会问既然格式差异这么大到底怎么共享我的答案是做“一个入口文件加一份适配索引”。对于每个技能包SKILL.md 是唯一的内容源头它保持跟 Claude Code 完全兼容的格式。同时我在技能包根目录维护一个AGENTS.md索引文件这个文件是给 Codex 看的里面用 Codex 更习惯的方式描述技能功能并指向 SKILL.md 和 references 下的具体文档。frontend-dev/ ├── SKILL.md # Claude Code / 内容主入口 ├── AGENTS.md # Codex 适配索引 └── references/ ├── component-guide.md └── page-structure.md这套结构的核心是让 SKILL.md 保持纯净不要在它里面写“针对某款工具专属”的内容。所有适配信息都放在 AGENTS.md 索引里哪个 Agent 需要哪层信息就去对应的文件里取。这样两边加载的底层知识是完全一致的只是读取路径和描述方式不同。3. 实操过程搭一套从零到一、可直接复用的统一管理方案3.1 环境准备与目录初始化开始之前先确认几件事。第一确认 Claude Code 和 Codex 都已经安装并至少跑通过一次这样它们的配置目录才会被创建出来。第二确认你的系统支持符号链接macOS 和 Linux 原生支持Windows 需要开发者模式或管理员权限这个后面单独讲。终端里先建统一仓库mkdir -p ~/.ai-skills/skills mkdir -p ~/.ai-skills/scripts cd ~/.ai-skills然后把一套技能放进去。以frontend-dev为例我直接建目录、写 SKILL.md--- name: frontend-dev description: 前端组件开发与页面结构设计规范适用于 React/Vue 项目。包括组件粒度拆分、Props 设计、状态管理选型和样式方案选择。 --- # 前端开发技能 当用户需要开发或修改前端页面时按以下流程工作 1. 先分析页面结构确定组件拆分的粒度保持每个组件职责单一。 2. 根据交互复杂度选择状态管理方案局部状态用组件内 state共享状态用轻量 store。 3. 样式方案优先使用 CSS Modules特殊情况需要 Tailwind 时先说明理由。 4. 组件实现遵循项目已有的代码风格不引入新的依赖。 ## 输出标准 - 组件文件包含类型定义、默认导出和注释说明。 - 样式文件与组件文件放置在同一个目录下。 - 不修改与当前任务无关的代码。 ## 参考文档 详细规范和示例见 references/ 目录下的文档。3.2 软链接打通把同一个技能包映射到两个工具目录目录初始化好之后关键动作就是建立软链接。先处理 Claude Code 侧mkdir -p ~/.claude/skills ln -s ~/.ai-skills/skills/frontend-dev ~/.claude/skills/frontend-dev然后处理 Codex 侧。Codex 的技能加载走 AGENTS.md所以不是把所有技能包都软链过去而是建一个只读目录把技能包软链进去再在 AGENTS.md 里指向它mkdir -p ~/.codex/skills ln -s ~/.ai-skills/skills/frontend-dev ~/.codex/skills/frontend-dev这里有个细节不要在 AGENTS.md 里写绝对路径指向~/.ai-skills下的原目录而是指向~/.codex/skills/frontend-dev。原因在于 Codex 在读取说明文件时对引用路径的解析不一定能正确展开~符号指向它自己的配置目录最稳妥。Windows 上执行软链接需要先确认开发人员模式已开启然后以非管理员身份运行New-Item -ItemType SymbolicLink -Path $HOME\.claude\skills\frontend-dev -Target $HOME\.ai-skills\skills\frontend-dev3.3 适配层配置给 Codex 写一份好用的 AGENTS.md 索引Codex 的 AGENTS.md 我维护在~/.codex/AGENTS.md内容是把所有可共享技能包登记进去每个条目指向对应目录下的文件# Codex 技能索引 以下技能包与 Claude Code 共享存放在 ~/.codex/skills 下。 ## 前端开发技能 当任务涉及前端组件开发、页面结构设计或样式方案选择时参考以下文件 - 技能入口~/.codex/skills/frontend-dev/SKILL.md - 组件规范~/.codex/skills/frontend-dev/references/component-guide.md - 页面结构~/.codex/skills/frontend-dev/references/page-structure.md ## 学术写作技能 当任务涉及论文结构、参考文献格式或学术表达优化时参考以下文件 - 技能入口~/.codex/skills/academic-writing/SKILL.md注意这里的写法要符合 Codex 渐进式披露的原则入口文件只做索引和触发条件说明不要在 AGENTS.md 里把 SKILL.md 的完整正文复制过来。这样 Codex 在普通编码任务中不会加载与当前任务无关的技能详情上下文空间留给真正需要的指令。3.4 验证共享是否生效三分钟跑通全流程配置都做完必须实测验证。我的验证步骤很固定先在 Claude Code 里输入#看技能列表里是否出现frontend-dev。选中后让它按技能里定义的规范生成一个简单组件重点看它有没有读取 references 目录里的规范文档。如果组件输出体现了 component-guide 里的约定说明加载成功。再切到 Codex在 agent 模式下输入一个前端相关的任务比如“按现有技能规范帮我生成一个用户列表组件”。观察它的响应路径正常的流程是它在处理前会去读取 AGENTS.md 索引然后找到 SKILL.md 和 references 文件输出风格和 Claude Code 应该高度一致。我实测的第一版方案有个容易踩的点技能包里的 references 文件用了相对路径引用Claude Code 能正确解析但 Codex 对相对路径的基准目录判断不一样有时候会 404。后来把所有索引文件里的引用路径统一改成从~/.codex/skills/出发的完整路径问题就消失了。4. 常见问题与排查技巧实录4.1 技能列表不显示检查链路按这个顺序来这是出现频率最高的问题。技能在 Claude Code 里不出现或者 Codex 读了但没生效先别急着怀疑代码按顺序查第一查路径。~/.claude/skills/或~/.codex/AGENTS.md里的路径拼写是不是完全正确多一个少一个斜杠都会出事。我习惯用ls -la确认软链接指向的路径存在且有效如果链接变成红色断链状态多半是源目录被移动了。第二查权限。有些 Agent 工具在启动时会跳过不可读的目录如果~/.ai-skills的权限设置成了700且属主不对Agent 进程可能读不到。统一设成755最稳妥。第三查格式。Claude Code 对 SKILL.md 的 frontmatter 解析很严格name和description缺失会导致技能被静默跳过。Codex 侧要确认 AGENTS.md 里的路径是它进程内能访问的路径而不是你当前 shell 的~。我遇到过最奇葩的一次是改了 SKILL.md 但始终不生效排查了半天才发现软链接指向的是一份旧副本真正的源文件早就换位置了。从那以后我给自己定了个规矩技能文件永远只在~/.ai-skills/skills/下改动其他任何目录里出现同名的 .md 文件都坚决不碰。4.2 Claude Code 和 Codex 回复风格不一致问题大概率出在适配层信息过载如果你确认两个工具都读到了技能文件但输出风格还是飘的那问题基本出在适配层的写法上。举个例子你在 AGENTS.md 里写了一大段关于技能用途的解释把 SKILL.md 的正文复述了一遍Codex 就会收到两份内容一份是索引里的转述一份是它实际去读的原文。两者措辞稍有出入Codex 就可能以索引里的转述为准输出自然和 Claude Code 不一致。适配层的最优写法是只写“什么时候用”和“去哪里读”不写“怎么做”。“怎么做”的唯一来源是 SKILL.md 和 references 目录。这样无论哪个 Agent 来读拿到的操作细节永远来自同一份源文件。还有一个容易被忽略的点references 目录里的规范文档尽量用事实性描述不要写“根据某某的偏好”“我们觉得”这类主观表达。Agent 读到主观表达时会产生自己的“理解”而两个 Agent 的理解方式不同输出就分叉了。4.3 Windows 环境下软链接没反应多半是权限和工具链问题Windows 上软链接的坑比较典型。很多人在 Windows 下执行New-Item创建符号链接时会因为未开启开发者模式而报错或者在 IDE 里看到链接建好了但代码工具不认。现在的 Windows 11 其实已经把开发者模式入口做得比较浅了在设置里搜“开发者模式”就能找到。开启后普通用户进程创建符号链接就不需要管理员权限了。但这里有个大坑很多代码编辑器或终端工具是以管理员身份运行的它们读取软链接的行为和普通用户进程不一样。你可能在 PowerShell 里创建链接没问题切到 VSCode 的终端里一跑发现路径解析不了。我的建议是统一用同一个非管理员用户运行终端、编辑器、Agent 工具不要混用管理员和非管理员进程。另外 Windows 下还有一种替代方案如果你实在搞不定符号链接可以用目录联接Junction代替New-Item -ItemType Junction -Path $HOME\.claude\skills\frontend-dev -Target $HOME\.ai-skills\skills\frontend-devJunction 在 Windows 下不需要开发者模式而且对于本地目录来说行为基本等同于符号链接只是不能跨卷使用。如果你的~/.ai-skills和~/.claude在不同磁盘分区Junction 就不适用还是得开开发者模式用符号链接。4.4 多技能包管理时的路径维护心得技能包多起来以后维护的重点会从“写技能”转移到“保持路径和引用的有序”。我的经验是维护一个总索引文件放在~/.ai-skills/README.md每新增一个技能包就在里面登记三个信息技能目录名、用途简述、AGENTS.md 登记状态。登记状态这个字段很关键它提醒你这个技能是否已经在 Codex 侧登记过。我吃过一次亏新增了一套数学建模相关的技能Claude Code 里用得挺好Codex 那边一直没登记直到某次 Codex 答非所问才想起来原来它根本没加载这套技能。为了避免下次再犯我把登记动作和技能创建动作绑定在一起每创建一个技能包顺手更新~/.ai-skills/README.md和~/.codex/AGENTS.md一件事做到底再开始下一个任务。这样虽然每次多花两分钟但整体维护成本低很多。技能文件的命名也值得花点心思。我建议用 kebab-case短横线分隔命名技能目录比如frontend-dev、math-modeling、academic-writing不要用空格和中文。原因有两个一是很多工具的路径解析对空格不友好二是 Agent 在自然语言理解时对 kebab-case 的识别准确率明显高于带特殊字符的命名。5. 进阶当技能超过 20 个这套方案怎么继续撑住5.1 按项目裁剪技能集而不是全量加载技能包到 20 个以上以后全量加载的副作用会出现每个 Agent 会话都带着一份很长的技能索引上下文空间被吃掉不少而且模型在选择技能时容易混淆相近用途的技能。我的做法是按项目类型做裁剪。在统一仓库之外每个具体项目目录下维护一份项目级的 AGENTS.md只在里面登记与本项目相关的技能包# 项目技能配置 本项目为 React 前端项目使用以下技能 - 前端开发技能~/.ai-skills/skills/frontend-dev/SKILL.md - 视觉还原技能~/.ai-skills/skills/visual-fidelity/SKILL.md结合你们团队或你自己的项目这就是最值得花时间维护的一份文件。项目级配置的优先级高于全局配置Codex 读项目级 AGENTS.md 时会把全局的忽略掉或做合并具体行为看版本但实测下来项目级聚焦信息的效果比全局全量加载好太多。Claude Code 侧也有类似机制。在项目根目录下建.claude/skills/目录把项目需要的技能包软链进去它就只加载这些。5.2 技能包版本管理与变更纪律技能文件也会迭代。改一个组件规范可能牵涉 SKILL.md 和 references 下的三四个文档。这种情况下最怕的是改到一半被打断留下一个中间状态两边 Agent 加载的内容不一致。我的做法是给每个技能包加一个CHANGELOG.md每次修改后记录一行变更摘要。同时在 SKILL.md 的 frontmatter 里加一个version字段--- name: frontend-dev description: 前端组件开发与页面结构设计规范。 version: 2.3.0 ---这样有两个好处。一是你自己排查问题时能快速确认当前生效的是哪个版本二是 Claude Code 和 Codex 输出内容风格不一致时可以对比两个工具到底加载的是不是同一版本。版本号不一定要用语义化版本用日期也行比如2025.06.11。关键是改一次动一次不要嫌麻烦。技能文件的版本管理本质上是在降低 Agent 行为的不确定性这个投入绝对值得。5.3 配合 Git 仓库做团队级共享如果你在团队里推行这套方案建议把~/.ai-skills整体变成一个 Git 仓库。团队成员 clone 下来以后各自执行一遍软链接脚本就能获得完全一致的技能集。我这里用 bash 维护了一个setup.sh核心逻辑很简单#!/usr/bin/env bash set -euo pipefail SKILLS_DIR$HOME/.ai-skills/skills CLAUDE_SKILLS$HOME/.claude/skills CODEX_SKILLS$HOME/.codex/skills mkdir -p $CLAUDE_SKILLS $CODEX_SKILLS for skill in $SKILLS_DIR/*/; do name$(basename $skill) ln -sfn $skill $CLAUDE_SKILLS/$name ln -sfn $skill $CODEX_SKILLS/$name done echo done注意ln -sfn里的-f参数强制执行覆盖避免重复执行时因为链接已存在而报错。-n参数是防止链接指向目录时被当作目录处理。这个脚本我在多台机器上跑过macOS 和 Linux 都正常。Windows 用户可以把对应逻辑写成 PowerShell 脚本核心就是把for循环遍历$HOME\.ai-skills\skills\*然后逐个创建符号链接。6. 从个人方案到通用习惯几点复盘心得回头整理这套方案时我最大的体会是技术难点其实不在软链接怎么建也不在 SKILL.md 怎么写而在于你有没有建立起“一份源、多处引用”的意识。很多人在多 Agent 之间维护技能第一反应是去复制文件因为有现成的目录可以粘贴。但复制一次就意味着后续每一次更新都要复制很多次长期来看时间成本非常高。我在实际使用中还发现了一个小技巧给每个技能包里的 SKILL.md 写 description 时刻意从 Claude Code 和 Codex 两个工具的视角各写一句。Claude Code 侧重触发场景描述Codex 侧重文件导航描述。但这两句话都放在同一个文件里用不同的小节区分。这样无论是哪个工具来读都能在第一时间理解技能的使用场景同时不会因为描述过短导致触发率下降。还有一个容易被忽视的点是 references 目录里的文档不要写得太长。Agent 在加载技能时references 里的文件是被按需读取的不会自动全量进入上下文。但这不代表可以肆无忌惮地堆内容。技能包的作用是给 Agent 提供工作规范和判断标准不是一本百科全书。把大量与日常任务无关的边界情况塞进 references反而会稀释重点。目前我维护的技能仓库里一共有 14 个技能包从前端开发到学术写作到数学建模都有。日常开发时Claude Code 和 Codex 的输出一致性已经能做到九成以上的相似度。剩下的一成差异主要来自两个工具底层的模型能力差异这个靠技能配置是拉不平的也不应该强行拉平。如果你现在正被多 Agent 技能维护搞得焦头烂额我建议先从最小闭环开始。挑两个最常用的技能包按上面的方案建好软链接和适配索引用两天时间观察效果。当你发现改一处文件两个工具同时生效时大概率就会想把所有技能都迁到统一仓库里来。 多Agent共享Skills统一管理：Claude Code与Codex配置实战
我记得第一次在 Claude Code 里折腾完一套 Skills兴冲冲切到 Codex 准备复用结果发现两边的加载机制完全不在一个频道上。后来查了一圈文档才明白Claude Code 认的是个人目录下的 SKILL.mdCodex 认的是 AGENTS.md 和结构化说明文件两边既不共用一套目录也不共用一套格式。这不只是多复制一份文件的问题——同一套技能在两边逐渐长出两个版本修了左边忘右边很快就是一笔糊涂账。这篇内容想聊的是一套多 Agent 共享的 Skills 统一管理方案。目标很明确同一个技能仓库Claude Code 和 Codex 都能用改动一处两边同时生效不再各自维护。文章里会讲清两套工具的加载机制差异、共享目录的规划方式、软链接与配置文件的落地做法以及我在实际操作中遇到的几个坑。适合正在同时使用多个编程 Agent、又不想被技能配置反复折磨的开发者。1. 为什么多 Agent 共用一个 Skills 目录比各搞各的更靠谱1.1 先搞清痛点你到底在重复维护什么先说个常见场景。你写了一套前端开发 Skills里面包括组件生成规范、Page 结构约定、样式方案选择逻辑一共三个技能文件。在 Claude Code 里用顺手了切到 Codex 发现它根本不读这个目录于是你照着 Codex 的规则又整理了一份。两边语法不一样描述一个长一个短用着用着你会发现 Claude Code 那边的技能更新了组件规范Codex 那边还是老一套。这个问题的本质不是“没复制文件”而是“同一份知识体被拆成了两套独立维护”。技能不是一次性写死的配置——它会随着项目规范、团队约定、你个人的工程习惯不断迭代。只要有两份副本存在同步就是永无止境的事。另一个更隐蔽的问题是上下文污染。很多人的做法是把 Claude Code 的 skills 目录整个拷给 Codex结果 Codex 加载了一大堆为 Claude Code 专属语法设计的说明文件。轻则浪费上下文窗口重则产生互相矛盾的指令Agent 的回复风格飘忽不定。1.2 方案选型统一仓库加软链接而不是复制粘贴我最终采用的方案是三层结构一个统一技能仓库作为唯一事实来源两个 Agent 的加载目录通过软链接指向仓库内部再加上一个按 Agent 区分的薄适配层。统一仓库解决的是版本一致性问题所有技能文件只存在一份改动直接对所有 Agent 生效。软链接解决的是路径识别问题Claude Code 有它固定的技能搜索目录Codex 也有它固定的说明文件目录两边不强行改变搜索逻辑而是把相同的内容“映射”过去。适配层解决的是语法差异问题两边真正读取的顶层文件可以不同但它们指向的内容是共享的。提示这套思路不光适用于 Claude Code 和 CodexOpenCode、Cline 这类支持自定义指令目录的工具都能套用。核心原则是“一份源、多处引用”永远不要用复制粘贴来管理技能文件。1.3 目录规划先搭一个不依赖厂商的中间层我建议把技能仓库放在~/.ai-skills/下不挂在任何一家工具的配置目录里。这个目录的好处是独立、干净后续就算某家 Agent 改了配置规范也不会牵连到你的技能源文件。目录内部按“技能包”组织每个技能包就是一个子目录~/.ai-skills/ ├── skills/ │ ├── frontend-dev/ │ │ ├── SKILL.md │ │ └── references/ │ │ ├── component-guide.md │ │ └── page-structure.md │ ├── academic-writing/ │ │ ├── SKILL.md │ │ └── references/ │ └── math-modeling/ │ ├── SKILL.md │ └── references/每个技能包内部用 SKILL.md 作为统一入口文件references 目录存放支持材料。这个结构参考了目前主流 Agent 工具的技能描述规范但刻意不写死某一家语法的专属字段为后面的多 Agent 适配留出余地。2. 核心细节解析Claude Code 与 Codex 的加载机制到底差在哪2.1 Claude Code 侧frontmatter 加 SKILL.md 的加载逻辑Claude Code 的技能加载走的是个人目录扫描机制。它会在~/.claude/skills/部分环境可能是项目级.claude/skills/下扫描所有子目录读取每个子目录里的 SKILL.md 文件解析文件头部的 YAML frontmatter把名称、描述、依赖项等元数据注册进技能列表。当你在对话中输入#时就会弹出已加载的技能列表选中后对应的完整指令和参考资料才会进入上下文。这个机制有个关键特点技能目录的名字和 SKILL.md 里的 name 字段是被分别对待的。目录名影响的是文件系统的组织方式name 字段才是 Agent 真正用来识别和引用技能的名称。我见过有人只改目录名不改 name结果 Agent 识别出的技能名还是旧的排查了半天。SKILL.md 的 frontmatter 至少要包含name和descriptiondescription 写得越精确Agent 在相关场景下主动调用技能的概率就越高。正文部分用 Markdown 写清楚技能的执行步骤、输入输出约定、质量标准和禁止事项。Claude Code 对正文的格式没有特别严格的约束它会把整个文件作为指令注入上下文但注入的内容不宜过长否则会占用宝贵的上下文空间。2.2 Codex 侧AGENTS.md 与说明文件体系的组织方式Codex 和 Claude Code 的策略不太一样。它更依赖 AGENTS.md 这种渐进式披露的结构化说明文件。Codex 在会话开始时读入的是入口级 AGENTS.md里面不会写满大段操作细节而是用路径引用方式告诉模型“每个领域的具体规范在哪个文件里”模型在处理具体任务时再去读取对应文件。这意味着 Codex 侧的“技能”本质上不是一个被注册的插件而是一个被组织过的知识空间。你想让 Claude Code 的一个技能包在 Codex 里可用不能直接丢一个 SKILL.md 进去而是要在 Codex 能读到的说明文件里写明这个技能包的位置、用途和读取路径。实际落地时我会在~/.codex/下维护一个统一的 AGENTS.md把~/.ai-skills/skills/下的技能包逐个登记进去。登记项不用太长说清楚技能名称、适用场景、入口文件路径即可细节让 Codex 在需要时自己去读。2.3 格式差异的适配思路一份内容两张说明书整理完两边机制你可能会问既然格式差异这么大到底怎么共享我的答案是做“一个入口文件加一份适配索引”。对于每个技能包SKILL.md 是唯一的内容源头它保持跟 Claude Code 完全兼容的格式。同时我在技能包根目录维护一个AGENTS.md索引文件这个文件是给 Codex 看的里面用 Codex 更习惯的方式描述技能功能并指向 SKILL.md 和 references 下的具体文档。frontend-dev/ ├── SKILL.md # Claude Code / 内容主入口 ├── AGENTS.md # Codex 适配索引 └── references/ ├── component-guide.md └── page-structure.md这套结构的核心是让 SKILL.md 保持纯净不要在它里面写“针对某款工具专属”的内容。所有适配信息都放在 AGENTS.md 索引里哪个 Agent 需要哪层信息就去对应的文件里取。这样两边加载的底层知识是完全一致的只是读取路径和描述方式不同。3. 实操过程搭一套从零到一、可直接复用的统一管理方案3.1 环境准备与目录初始化开始之前先确认几件事。第一确认 Claude Code 和 Codex 都已经安装并至少跑通过一次这样它们的配置目录才会被创建出来。第二确认你的系统支持符号链接macOS 和 Linux 原生支持Windows 需要开发者模式或管理员权限这个后面单独讲。终端里先建统一仓库mkdir -p ~/.ai-skills/skills mkdir -p ~/.ai-skills/scripts cd ~/.ai-skills然后把一套技能放进去。以frontend-dev为例我直接建目录、写 SKILL.md--- name: frontend-dev description: 前端组件开发与页面结构设计规范适用于 React/Vue 项目。包括组件粒度拆分、Props 设计、状态管理选型和样式方案选择。 --- # 前端开发技能 当用户需要开发或修改前端页面时按以下流程工作 1. 先分析页面结构确定组件拆分的粒度保持每个组件职责单一。 2. 根据交互复杂度选择状态管理方案局部状态用组件内 state共享状态用轻量 store。 3. 样式方案优先使用 CSS Modules特殊情况需要 Tailwind 时先说明理由。 4. 组件实现遵循项目已有的代码风格不引入新的依赖。 ## 输出标准 - 组件文件包含类型定义、默认导出和注释说明。 - 样式文件与组件文件放置在同一个目录下。 - 不修改与当前任务无关的代码。 ## 参考文档 详细规范和示例见 references/ 目录下的文档。3.2 软链接打通把同一个技能包映射到两个工具目录目录初始化好之后关键动作就是建立软链接。先处理 Claude Code 侧mkdir -p ~/.claude/skills ln -s ~/.ai-skills/skills/frontend-dev ~/.claude/skills/frontend-dev然后处理 Codex 侧。Codex 的技能加载走 AGENTS.md所以不是把所有技能包都软链过去而是建一个只读目录把技能包软链进去再在 AGENTS.md 里指向它mkdir -p ~/.codex/skills ln -s ~/.ai-skills/skills/frontend-dev ~/.codex/skills/frontend-dev这里有个细节不要在 AGENTS.md 里写绝对路径指向~/.ai-skills下的原目录而是指向~/.codex/skills/frontend-dev。原因在于 Codex 在读取说明文件时对引用路径的解析不一定能正确展开~符号指向它自己的配置目录最稳妥。Windows 上执行软链接需要先确认开发人员模式已开启然后以非管理员身份运行New-Item -ItemType SymbolicLink -Path $HOME\.claude\skills\frontend-dev -Target $HOME\.ai-skills\skills\frontend-dev3.3 适配层配置给 Codex 写一份好用的 AGENTS.md 索引Codex 的 AGENTS.md 我维护在~/.codex/AGENTS.md内容是把所有可共享技能包登记进去每个条目指向对应目录下的文件# Codex 技能索引 以下技能包与 Claude Code 共享存放在 ~/.codex/skills 下。 ## 前端开发技能 当任务涉及前端组件开发、页面结构设计或样式方案选择时参考以下文件 - 技能入口~/.codex/skills/frontend-dev/SKILL.md - 组件规范~/.codex/skills/frontend-dev/references/component-guide.md - 页面结构~/.codex/skills/frontend-dev/references/page-structure.md ## 学术写作技能 当任务涉及论文结构、参考文献格式或学术表达优化时参考以下文件 - 技能入口~/.codex/skills/academic-writing/SKILL.md注意这里的写法要符合 Codex 渐进式披露的原则入口文件只做索引和触发条件说明不要在 AGENTS.md 里把 SKILL.md 的完整正文复制过来。这样 Codex 在普通编码任务中不会加载与当前任务无关的技能详情上下文空间留给真正需要的指令。3.4 验证共享是否生效三分钟跑通全流程配置都做完必须实测验证。我的验证步骤很固定先在 Claude Code 里输入#看技能列表里是否出现frontend-dev。选中后让它按技能里定义的规范生成一个简单组件重点看它有没有读取 references 目录里的规范文档。如果组件输出体现了 component-guide 里的约定说明加载成功。再切到 Codex在 agent 模式下输入一个前端相关的任务比如“按现有技能规范帮我生成一个用户列表组件”。观察它的响应路径正常的流程是它在处理前会去读取 AGENTS.md 索引然后找到 SKILL.md 和 references 文件输出风格和 Claude Code 应该高度一致。我实测的第一版方案有个容易踩的点技能包里的 references 文件用了相对路径引用Claude Code 能正确解析但 Codex 对相对路径的基准目录判断不一样有时候会 404。后来把所有索引文件里的引用路径统一改成从~/.codex/skills/出发的完整路径问题就消失了。4. 常见问题与排查技巧实录4.1 技能列表不显示检查链路按这个顺序来这是出现频率最高的问题。技能在 Claude Code 里不出现或者 Codex 读了但没生效先别急着怀疑代码按顺序查第一查路径。~/.claude/skills/或~/.codex/AGENTS.md里的路径拼写是不是完全正确多一个少一个斜杠都会出事。我习惯用ls -la确认软链接指向的路径存在且有效如果链接变成红色断链状态多半是源目录被移动了。第二查权限。有些 Agent 工具在启动时会跳过不可读的目录如果~/.ai-skills的权限设置成了700且属主不对Agent 进程可能读不到。统一设成755最稳妥。第三查格式。Claude Code 对 SKILL.md 的 frontmatter 解析很严格name和description缺失会导致技能被静默跳过。Codex 侧要确认 AGENTS.md 里的路径是它进程内能访问的路径而不是你当前 shell 的~。我遇到过最奇葩的一次是改了 SKILL.md 但始终不生效排查了半天才发现软链接指向的是一份旧副本真正的源文件早就换位置了。从那以后我给自己定了个规矩技能文件永远只在~/.ai-skills/skills/下改动其他任何目录里出现同名的 .md 文件都坚决不碰。4.2 Claude Code 和 Codex 回复风格不一致问题大概率出在适配层信息过载如果你确认两个工具都读到了技能文件但输出风格还是飘的那问题基本出在适配层的写法上。举个例子你在 AGENTS.md 里写了一大段关于技能用途的解释把 SKILL.md 的正文复述了一遍Codex 就会收到两份内容一份是索引里的转述一份是它实际去读的原文。两者措辞稍有出入Codex 就可能以索引里的转述为准输出自然和 Claude Code 不一致。适配层的最优写法是只写“什么时候用”和“去哪里读”不写“怎么做”。“怎么做”的唯一来源是 SKILL.md 和 references 目录。这样无论哪个 Agent 来读拿到的操作细节永远来自同一份源文件。还有一个容易被忽略的点references 目录里的规范文档尽量用事实性描述不要写“根据某某的偏好”“我们觉得”这类主观表达。Agent 读到主观表达时会产生自己的“理解”而两个 Agent 的理解方式不同输出就分叉了。4.3 Windows 环境下软链接没反应多半是权限和工具链问题Windows 上软链接的坑比较典型。很多人在 Windows 下执行New-Item创建符号链接时会因为未开启开发者模式而报错或者在 IDE 里看到链接建好了但代码工具不认。现在的 Windows 11 其实已经把开发者模式入口做得比较浅了在设置里搜“开发者模式”就能找到。开启后普通用户进程创建符号链接就不需要管理员权限了。但这里有个大坑很多代码编辑器或终端工具是以管理员身份运行的它们读取软链接的行为和普通用户进程不一样。你可能在 PowerShell 里创建链接没问题切到 VSCode 的终端里一跑发现路径解析不了。我的建议是统一用同一个非管理员用户运行终端、编辑器、Agent 工具不要混用管理员和非管理员进程。另外 Windows 下还有一种替代方案如果你实在搞不定符号链接可以用目录联接Junction代替New-Item -ItemType Junction -Path $HOME\.claude\skills\frontend-dev -Target $HOME\.ai-skills\skills\frontend-devJunction 在 Windows 下不需要开发者模式而且对于本地目录来说行为基本等同于符号链接只是不能跨卷使用。如果你的~/.ai-skills和~/.claude在不同磁盘分区Junction 就不适用还是得开开发者模式用符号链接。4.4 多技能包管理时的路径维护心得技能包多起来以后维护的重点会从“写技能”转移到“保持路径和引用的有序”。我的经验是维护一个总索引文件放在~/.ai-skills/README.md每新增一个技能包就在里面登记三个信息技能目录名、用途简述、AGENTS.md 登记状态。登记状态这个字段很关键它提醒你这个技能是否已经在 Codex 侧登记过。我吃过一次亏新增了一套数学建模相关的技能Claude Code 里用得挺好Codex 那边一直没登记直到某次 Codex 答非所问才想起来原来它根本没加载这套技能。为了避免下次再犯我把登记动作和技能创建动作绑定在一起每创建一个技能包顺手更新~/.ai-skills/README.md和~/.codex/AGENTS.md一件事做到底再开始下一个任务。这样虽然每次多花两分钟但整体维护成本低很多。技能文件的命名也值得花点心思。我建议用 kebab-case短横线分隔命名技能目录比如frontend-dev、math-modeling、academic-writing不要用空格和中文。原因有两个一是很多工具的路径解析对空格不友好二是 Agent 在自然语言理解时对 kebab-case 的识别准确率明显高于带特殊字符的命名。5. 进阶当技能超过 20 个这套方案怎么继续撑住5.1 按项目裁剪技能集而不是全量加载技能包到 20 个以上以后全量加载的副作用会出现每个 Agent 会话都带着一份很长的技能索引上下文空间被吃掉不少而且模型在选择技能时容易混淆相近用途的技能。我的做法是按项目类型做裁剪。在统一仓库之外每个具体项目目录下维护一份项目级的 AGENTS.md只在里面登记与本项目相关的技能包# 项目技能配置 本项目为 React 前端项目使用以下技能 - 前端开发技能~/.ai-skills/skills/frontend-dev/SKILL.md - 视觉还原技能~/.ai-skills/skills/visual-fidelity/SKILL.md结合你们团队或你自己的项目这就是最值得花时间维护的一份文件。项目级配置的优先级高于全局配置Codex 读项目级 AGENTS.md 时会把全局的忽略掉或做合并具体行为看版本但实测下来项目级聚焦信息的效果比全局全量加载好太多。Claude Code 侧也有类似机制。在项目根目录下建.claude/skills/目录把项目需要的技能包软链进去它就只加载这些。5.2 技能包版本管理与变更纪律技能文件也会迭代。改一个组件规范可能牵涉 SKILL.md 和 references 下的三四个文档。这种情况下最怕的是改到一半被打断留下一个中间状态两边 Agent 加载的内容不一致。我的做法是给每个技能包加一个CHANGELOG.md每次修改后记录一行变更摘要。同时在 SKILL.md 的 frontmatter 里加一个version字段--- name: frontend-dev description: 前端组件开发与页面结构设计规范。 version: 2.3.0 ---这样有两个好处。一是你自己排查问题时能快速确认当前生效的是哪个版本二是 Claude Code 和 Codex 输出内容风格不一致时可以对比两个工具到底加载的是不是同一版本。版本号不一定要用语义化版本用日期也行比如2025.06.11。关键是改一次动一次不要嫌麻烦。技能文件的版本管理本质上是在降低 Agent 行为的不确定性这个投入绝对值得。5.3 配合 Git 仓库做团队级共享如果你在团队里推行这套方案建议把~/.ai-skills整体变成一个 Git 仓库。团队成员 clone 下来以后各自执行一遍软链接脚本就能获得完全一致的技能集。我这里用 bash 维护了一个setup.sh核心逻辑很简单#!/usr/bin/env bash set -euo pipefail SKILLS_DIR$HOME/.ai-skills/skills CLAUDE_SKILLS$HOME/.claude/skills CODEX_SKILLS$HOME/.codex/skills mkdir -p $CLAUDE_SKILLS $CODEX_SKILLS for skill in $SKILLS_DIR/*/; do name$(basename $skill) ln -sfn $skill $CLAUDE_SKILLS/$name ln -sfn $skill $CODEX_SKILLS/$name done echo done注意ln -sfn里的-f参数强制执行覆盖避免重复执行时因为链接已存在而报错。-n参数是防止链接指向目录时被当作目录处理。这个脚本我在多台机器上跑过macOS 和 Linux 都正常。Windows 用户可以把对应逻辑写成 PowerShell 脚本核心就是把for循环遍历$HOME\.ai-skills\skills\*然后逐个创建符号链接。6. 从个人方案到通用习惯几点复盘心得回头整理这套方案时我最大的体会是技术难点其实不在软链接怎么建也不在 SKILL.md 怎么写而在于你有没有建立起“一份源、多处引用”的意识。很多人在多 Agent 之间维护技能第一反应是去复制文件因为有现成的目录可以粘贴。但复制一次就意味着后续每一次更新都要复制很多次长期来看时间成本非常高。我在实际使用中还发现了一个小技巧给每个技能包里的 SKILL.md 写 description 时刻意从 Claude Code 和 Codex 两个工具的视角各写一句。Claude Code 侧重触发场景描述Codex 侧重文件导航描述。但这两句话都放在同一个文件里用不同的小节区分。这样无论是哪个工具来读都能在第一时间理解技能的使用场景同时不会因为描述过短导致触发率下降。还有一个容易被忽视的点是 references 目录里的文档不要写得太长。Agent 在加载技能时references 里的文件是被按需读取的不会自动全量进入上下文。但这不代表可以肆无忌惮地堆内容。技能包的作用是给 Agent 提供工作规范和判断标准不是一本百科全书。把大量与日常任务无关的边界情况塞进 references反而会稀释重点。目前我维护的技能仓库里一共有 14 个技能包从前端开发到学术写作到数学建模都有。日常开发时Claude Code 和 Codex 的输出一致性已经能做到九成以上的相似度。剩下的一成差异主要来自两个工具底层的模型能力差异这个靠技能配置是拉不平的也不应该强行拉平。如果你现在正被多 Agent 技能维护搞得焦头烂额我建议先从最小闭环开始。挑两个最常用的技能包按上面的方案建好软链接和适配索引用两天时间观察效果。当你发现改一处文件两个工具同时生效时大概率就会想把所有技能都迁到统一仓库里来。