如果你同时在用 Claude Code 和 Codex而且已经往技能清单里塞了两位数以上的 Skill大概率经历过我上个月那种崩溃一个刚改好的 code-review 技能Claude Code 这边用的是新规则Codex 那边还在跑旧版本社区里看到一份不错的前端开发 skills 合集下载解压之后发现目录结构两边不通用更烦的是给每个工具各维护一份文件每次更新都要想这次同步过去没有。我当时在十几个 skill 文件里来回复制粘贴了二十多回实在受不了于是专门做了一套统一管理方案把全部 Skill 的源文件收敛到一个 Git 仓库通过符号链接和同步脚本挂载到 Claude Code 和 Codex 各自的 skills 目录实现一套 Skills 在多个 Agent 之间共享。这套结构我用了近两个月中间踩了不少坑今天把整个方案和排查过程完整写出来给同样被多 Agent 技能管理折磨的人一个可直接照抄的答案。1. 为什么坚持一套 Skills多 Agent 共享各自为战的代价很多人的最初状态就是各放各的Claude Code 的 skill 放~/.claude/skills/Codex 的 skill 放~/.codex/skills/两边井水不犯河水看似没什么毛病。但只要你认真用了两个 Agent并且技能数量开始增加各放各的会在三个层面同时拖后腿。1.1 双份维护带来的内容漂移我吃过最直接的亏是规则不统一。上上个月我想让两个 Agent 在代码审查时都遵守一套新的安全检测规则于是先改了 Claude Code 里的 code-review 技能把必须检查密钥硬编码、SQL 拼接、反序列化入口这几条加了进去当时想着回头再改 Codex 那边的文件结果连着两天忙别的完全忘了。后来在 Codex 里跑了一次 review它给的检查清单还是老的漏掉了新加的密钥检测项。这不是 Codex 不行是我根本没把最新规则同步过去。这种问题在一个人同时维护两份文件时几乎无法避免因为你多一次复制粘贴就多一次版本不一致的机会。更隐蔽的是 YAML frontmatter 的字段差异。两个工具对 skill 元数据的解析策略不完全一样同一个 frontmatter 里多写一个不认识的字段Claude Code 可能只是忽略而 Codex 可能整个文件解析失败反过来也一样。手动复制文件的时候很容易顺手把上一份文件里为另一个工具调整过的字段一起带过去结果一边能跑一边直接不识别调试半天才发现是字段兼容问题。1.2 没有版本概念等于没有后悔药手动复制意味着你几乎没有版本管理昨天改的 html2md 技能到底改到哪个文件了今天想回退到三天前能用的版本完全无从下手。虽然两个工具各自的 skills 目录本质也是磁盘上的普通文件但大家维护的时候几乎不会想到去 git init。技能文件这种需要频繁迭代的内容没有 git 历史保护一旦改坏就要靠记忆手修效率极低。等到技能数量涨到二十几个回滚一个坏掉的技能几乎等于重写一遍。1.3 统一管理方案要解决的三件事所以我在设计这套一套 Skills多 Agent 共享方案时给自己定了三个硬指标单一事实源所有 skill 的源文件只在一个目录里维护这个目录本身就是 git 仓库目录外的文件都不允许作为可修改副本存在。一致加载路径通过符号链接和同步脚本把源目录映射到不同 Agent 各自约定的技能加载目录agent 扫描时看到的仍是标准结构但实际指向同一份源文件。可回滚可审计所有变更走 git每个 skill 每次调整都有 commit 记录出问题直接git revert。这三个指标看起来简单真做起来牵扯的细节不少。下面先把两个工具的技能机制讲明白不然链接建得再漂亮格式不兼容还是白搭。2. 先摸清两家底细Claude Code 与 Codex 的 Skills 机制差异很多人以为既然都有 skills 目录那就复用了真这么干会立刻翻车。两个 Agent 的 skills 机制在目录位置、元数据解析、触发策略上都有差别共享的前提是先把这些差异理清。2.1 Claude Code 的 Skills目录约定与自动触发Claude Code 的技能体系目前是用户级与项目级两层。用户级目录是~/.claude/skills/项目级目录是项目下的.claude/skills/每个技能独立建一个子目录子目录里面必须有一个SKILL.md文件这个文件顶部是 YAML frontmatter下面是 Markdown 正文。Claude Code 在会话启动时或需要时会扫描可用的技能读取每个 SKILL.md 的 frontmatter 中的 name 和 description把这些元数据作为候选能力表交给模型当模型判断当前任务与某个 description 匹配时就会把对应 SKILL.md 正文加载进上下文来指导执行。所以 description 写得好不好直接决定技能会不会被正确触发。如果 description 写得太宽泛模型大概率不会在真正需要时想起来调用如果写得太窄又会错过相似任务的触发机会。2.2 Codex 的 Skills与 AGENTS.md 并存的能力体系Codex 这边的机制和 Claude Code 相似但不一样。它之前主要依赖项目里的 AGENTS.md 作为全局指导文件后来也引入了独立技能目录默认在~/.codex/skills/下同样以 SKILL.md 文件为技能入口。不同版本的 Codex 对这个功能的支持程度有差异有的版本还提供codex skills add之类的子命令来注册技能。我本机上观察到的行为是Codex 会扫描技能目录里的 SKILL.md解析 frontmatter再根据用户任务的语义决定是否调用对应技能。需要特别提醒的是Codex 的版本迭代很快不同小版本对 skills 目录的扫描策略可能有差异。所以做统一管理前先执行codex --version确认手上的版本再看一眼codex skills --help的输出确认支持哪些参数。不要照搬网上三个月前的教程命令格式很可能已经变了。顺带回答一个被问得比较多的问题harness 和 agent 有什么区别。简单说harness 是 Agent 运行的执行框架负责工具调度、会话管理、命令分发agent 是模型本身加上下文、加技能后的产物。skills 是给 agent 加能力包的手段和 harness 不在同一个层面所以别把它们混为一谈。2.3 两边差异对照表为了直观我把目前我机器上两个工具的实际差异整理成了一张表对比项Claude CodeCodex用户级技能目录~/.claude/skills/~/.codex/skills/项目级技能目录.claude/skills/项目内可通过 AGENTS.md 引用技能本体通常在用户级目录技能文件SKILL.mdSKILL.md元数据YAML frontmattername、description 等同样使用 YAML frontmatter但兼容字段集合更小触发方式按 description 语义匹配 手动触发按 description 语义匹配自定义脚本支持在 SKILL.md 里引用同目录脚本可引用但路径解析方式可能不同这张表的核心结论是两者没有本质冲突都认 SKILL.md 和 YAML frontmatter这给了一套 Skills 两处引用的实现基础但元数据字段的兼容范围不一样这就要求我们写 frontmatter 时只保留两边都认的最小公共字段而不是把某一方特有的扩展字段写进去。3. 统一管理核心方案一个 Git 仓库 符号链接打通既然两边的目录位置不同但文件格式大体兼容最直觉的做法就是让多个目录都指向同一份源文件。我采用的方式是一个统一仓库 一组符号链接 一个同步脚本。3.1 仓库目录规划我建议在用户主目录下建一个专门的 ai-skills 目录并把它初始化为 git 仓库mkdir -p ~/ai-skills cd ~/ai-skills git init仓库内部按一个技能一个子目录组织~/ai-skills/ README.md code-review/ SKILL.md scripts/ review-rules.json frontend-dev/ SKILL.md templates/ component.stub.tsx html2md/ SKILL.md academic-research/ SKILL.md每个子目录都包含一个 SKILL.md这是被 Agent 扫描的入口同目录下可以放这个技能依赖的脚本、模板、数据文件Agent 在执行时按相对路径引用它们。比如 frontend-dev 里的模板文件就是让 Agent 在生成组件时照着模板结构来。为什么不用一个扁平的大 SKILL.md 把所有技能塞进去因为两个 Agent 的扫描器都要求一个技能一个目录塞在一起会被当成一个整体扫描命名和触发都会混乱。保持目录粒度和 Agent 的内部模型一致迁移成本最低。3.2 用符号链接打通两个 skills 目录统一仓库建好之后关键一步是在 Claude Code 和 Codex 的 skills 目录里建立链接。符号链接的意思是~/.claude/skills/code-review这个路径本身不是实体目录而是一个指向~/ai-skills/code-review的快捷方式。Agent 扫描时打开这个路径看到的是源目录里的内容我们修改源目录里的 SKILL.md所有链接点立即生效不需要同步、不需要拷贝。先确保两边的用户级 skills 目录存在mkdir -p ~/.claude/skills ~/.codex/skills然后手动为第一个技能建立链接尝试验证ln -s ~/ai-skills/code-review ~/.claude/skills/code-review ln -s ~/ai-skills/code-review ~/.codex/skills/code-review验证一下链接是否有效ls -la ~/.claude/skills/code-review cat ~/.claude/skills/code-review/SKILL.md如果 cat 能看到内容说明 Agent 也能读。接下来为仓库里所有技能批量建立链接就轮到同步脚本上场了。3.3 同步脚本 sync-skills.sh一个可复制的批次脚本遍历统一仓库下的每个子目录检查是否存在 SKILL.md存在就在两个目标目录里建立链接#!/usr/bin/env bash set -euo pipefail SOURCE_DIR$HOME/ai-skills CLAUDE_SKILLS$HOME/.claude/skills CODEX_SKILLS$HOME/.codex/skills mkdir -p $CLAUDE_SKILLS $CODEX_SKILLS for skill_dir in $SOURCE_DIR/*/; do name$(basename $skill_dir) if [ ! -f $skill_dir/SKILL.md ]; then echo skip: $name (no SKILL.md) continue fi ln -sfn $SOURCE_DIR/$name $CLAUDE_SKILLS/$name ln -sfn $SOURCE_DIR/$name $CODEX_SKILLS/$name echo linked: $name - $SOURCE_DIR/$name done echo sync done.脚本的逻辑不复杂但有几个关键点要解释。set -euo pipefail是为了在出错时快速失败避免执行一半还继续往下跑。ln -sfn中的-f强制覆盖已存在的链接-n防止把目标目录当链接目标继续层层嵌套这两个参数组合在重复执行脚本时尤其重要。for skill_dir in $SOURCE_DIR/*/只遍历目录自动跳过根目录下的 README.md 等普通文件。把这个脚本放在~/ai-skills/sync-skills.sh加可执行权限chmod x ~/ai-skills/sync-skills.sh ~/ai-skills/sync-skills.sh之后每次在仓库里新增或删除技能只要重新跑一遍脚本两个 Agent 的目录就会同步到最新状态。Windows 用户的话符号链接需要用mklink /D创建并且需要开发者模式或管理员权限PowerShell 脚本逻辑类似但ln换成New-Item -ItemType SymbolicLink。要注意的是Windows 下 git clone 一个带符号链接的仓库时默认不一定保留链接语义设置git config core.symlinks true才能保证签出的仓库里链接仍然有效。如果嫌麻烦Windows 上直接退化为复制脚本 增量同步也是可行的后面踩坑部分会详细对比。4. 让一份 Skill 同时兼容两个 Agent模板、frontmatter 与入口配置链接是搭好了但技能内容本身如果只适配某一边一旦被另一个 Agent 加载轻则不生效重则报错。所以统一管理方案里最重要的一环是写一份两边都兼容的 SKILL.md 规范。4.1 统一 frontmatter 模板我目前所有技能用的 frontmatter 模板是--- name: code-review description: 当用户要求审查代码质量、定位潜在 Bug、检查安全漏洞或提交 PR 审查意见时使用。输入是代码片段或 diff输出是分条列出问题等级、风险点和具体修改建议。 ---这段 frontmatter 里我只用了两个字段name 和 description。这是两个 Agent 都认的核心字段。不要往里塞 only-tools、metadata 之类只在某一方文档里出现的扩展字段因为共享仓库一旦被另一方读取解析器遇到不认识的字段可能直接失败。你想加自定义信息放到正文里比放到 frontmatter 里安全得多。name 的命名规范建议统一用小写字母加短横线比如 frontend-dev、code-review不要用空格和中文。虽然部分 Agent 可能容忍中文名但链接路径、脚本引用、命令行调用都会遇到麻烦没必要冒险。description 的写法必须覆盖什么任务用、输入是什么、输出是什么。两个 Agent 读取 description 时通常会把整段文本送去模型做语义匹配所以描述不要写成关键词堆砌要写成完整的句子组合让模型能准确理解触发边界。4.2 正文结构的统一约定SKILL.md 的正文部分我按固定结构组织这样每个技能看起来都一样Agent 处理起来也更稳定适用场景与触发条件用几行明确说明什么时候该用这个技能什么时候不该用。核心执行步骤用数字编号列出 3 到 10 步一步步告诉模型怎么做。参考命令与示例给出可直接执行的命令或调用示例尽量贴实际。已知限制与常见坑把容易出错的地方写清楚能显著减少 Agent 的试错。这里有个重要经验SKILL.md 不需要写得很长我一般控制在 150 行以内。原因是技能被触发后正文内容会被加载进模型上下文占的是宝贵的 token 配额。写得太多技能还没发挥作用上下文先被挤爆了。把核心步骤和关键限制写清楚剩下的让模型用它的知识补全反而是更高效的用法。我早期吃过一个亏在某技能里把整个工具的使用手册都拷了进去约四百行结果每一次触发都会多消耗几千 token会话上下文很快见底。后来把冗余示例全部精简只留下最关键的部分效果反而更好。4.3 CLAUDE.md 与 AGENTS.md 的配合使用除了 SKILL.md 本身两个 Agent 还会各自读取项目级或全局的指导文件Claude Code 认 CLAUDE.mdCodex 认 AGENTS.md。这两个文件不是技能但它们承担着告诉 Agent 去哪找技能、什么时候该用技能的任务。我的做法是在每个项目根目录维护一份极简的 CLAUDE.md 和 AGENTS.md里面都会写一段固定的技能索引## Available Skills - code-review: 提交 PR 前必须执行代码审查 - frontend-dev: 涉及 React 组件开发时使用同时在用户级全局位置也放一份指向常用技能的说明。这样即使 SKILL.md 的 description 在某个场景下让模型犹豫不决项目级指导文件也能直接把模型引导到目标技能。两个文件内容保持一致配合统一仓库的符号链接整个技能体系才算完整接通。5. 容易翻车的几个地方切换端点失败、链接失效与扫描缓存统一管理方案跑顺之后真正令人头疼的反而不是方案本身而是各种环境细节。这一节我把实际使用中最容易翻车的几个问题展开讲包括排查思路而不是直接给结论。5.1 cc-switch 切换本地端点失败的排查思路有不少人在切换 Codex 的 endpoint 配置时遇到过类似 cc switch local endpoint failed while handling codex endpoint /responses 的报错网上对应的讨论也不少。这个报错看着吓人其实绝大多数情况跟你的技能仓库没关系而是切换工具在修改本地配置时出了偏差。我排查这类问题一般按这个顺序走看配置内容。cc-switch 这类工具本质上是帮你改 Agent 的配置文件、切换不同的 API 供应商或端点。先打开它生成的配置文件核对目标端点的 baseURL、模型名、密钥字段是否都写对了。很多时候是切换时少了一项配置导致 Agent 在访问 /responses 路径时拿不到合法响应。确认目标服务是否真的在监听。如果是连本地服务先用命令确认端口和进程状态例如lsof -i :端口号或者netstat -ano | findstr 端口号如果服务没起来切过去自然报 failed。看日志。切换工具一般会在用户目录下留日志文件翻最后几十行错误原因通常会写得比界面里更直白。兜底办法直接绕过切换工具手工编辑 Agent 自己的配置文件把 baseURL 和 API 密钥写上然后重启会话看问题是否消失。补充一句/responses 是某些端点协议里的标准请求路径如果你看到 failed while handling 这个位置说明请求已经发出去了只是处理环节挂掉了跟技能文件本身完全没有关系不用去怀疑刚才建的符号链接。5.2 符号链接在同步盘和权限条件下失效符号链接方案最大的敌人是各种同步工具。我一开始把 ~/ai-skills 仓库放在 iCloud Drive 同步目录下结果发现 iCloud 对符号链接的支持非常不友好它要么不识别链接要么把链接当成普通文件处理最终导致 ~/.claude/skills/code-review 变成一个悬空链接Agent 扫描时直接跳过。这个问题的根源是你的源目录和链接目录分别处于不同的同步层级里云同步的冲突解决策略没法理解快捷方式这种概念。所以我的建议是如果要用符号链接源仓库务必放在本地非同步目录比如 ~/ai-skills不要放在 iCloud、OneDrive、企业网盘等会做文件同步的目录目标 skills 目录也要在本地。权限方面还有一个容易忽略的点如果 ~/.claude 或 ~/.codex 目录属于 root 或者别的用户ln -sfn会失败。用ls -ld检查两个目录的所有者不对就先 chown 回来。我自己在服务器上用普通用户跑 Codex 时就遇到过这种情况目录是容器挂载出来的所有者对不上排查了半天。5.3 Agent 扫描缓存与新技能不生效一个非常容易误解的问题是我刚建好链接立刻去命令行里让 Agent 用新技能结果它完全没有反应。这不是链接建错了而是 Agent 的技能扫描发生在会话启动阶段或特定时机。Claude Code 和 Codex 通常会在启动新会话时读取技能列表你开着旧会话追加提问它可能不会重新扫描技能目录。正确的验证方式是开一个全新的会话先直接问你有哪些可用技能看输出里有没有包含刚加的那个技能没有的话再检查链接和 frontmatter。另一个技巧是先用命令行手动触发技能确认技能本身可用再考察自动语义匹配是否触发。Windows 下还有一个坑mklink /D创建的是目录符号链接但如果你用普通用户权限执行会提示权限不足需要先开启开发者模式或者用管理员权限的终端执行。另外 git 在 Windows 上默认不开启符号链接支持把仓库 clone 到 Windows 机器时链接可能变成普通文本文件需要在 git config 里设置 core.symlinks true并且使用支持符号链接的文件系统。6. 进阶玩法版本管理、团队协作与 Skill 质量检查基础方案跑通后统一管理能带来的收益其实远不止两个 Agent 用同一份文件这么简单。很多衍生价值是在使用过程中慢慢被放大的。6.1 把社区热门技能包管起来我身边不少人会下一些社区里很火的技能合集比如那套叫 superpower skills 的系列涵盖了很多任务拆解和自动化执行的技巧还有专门针对前端开发、渗透测试、学术研究等不同方向的 skills 包。把这些外部技能纳入统一仓库时我建议不要直接整个目录拷进来就完事而是先想清楚维护关系。如果上游更新很频繁且你不需要改动内容可以用 git submodule 把它挂在 ai-skills 仓库下每次git submodule update就能拉最新版如果上游更新不活跃或者你已经对内容做了大量本地化改造就直接复制进仓库完全接管后续维护。核心原则是不要让一份代码有两个维护入口。我在管理前端开发 skill 包时就是先复制后改造因为社区模板里很多组件格式跟我的项目习惯不一致改完之后再挂到两个 Agent 上使用效果比原版好很多。6.2 多台机器自动同步如果你像我一样有办公电脑、笔记本和服务器三个环境统一仓库只有一份但源文件要出现在所有机器的本地磁盘上链接才有意义。最简单的做法是在每台机器上都 clone 一遍 ai-skills 仓库然后跑一次 sync-skills.sh。手动操作虽然可行但偶尔会漏。我后来用一个 cron 任务来自动化这一步*/15 * * * * cd ~/ai-skills git pull --ff-only /dev/null 21 ~/ai-skills/sync-skills.sh /dev/null 21每 15 分钟检查一次仓库远程更新有则拉取然后重建所有链接。注意多台机器协作时配置文件里的密钥和敏感信息不要放进 ai-skills 仓库仓库里只放技能内容涉及个人密钥的地方用环境变量引用避免把明文带进 git 历史。6.3 给技能仓库加一道质量检查技能数量超过二十个之后光靠肉眼检查 frontmatter 已经不可靠了。我在仓库里放了一个很小的校验脚本 skill-lint.sh逻辑并不复杂#!/usr/bin/env bash for skill_dir in ~/ai-skills/*/; do name$(basename $skill_dir) file$skill_dir/SKILL.md [ -f $file ] || { echo error: $name missing SKILL.md; exit 1; } grep -q ^name: $file || { echo error: $name no name field; exit 1; } grep -q ^description: $file || { echo error: $name no description field; exit 1; } echo ok: $name done我还会在每次 git commit 之前跑一遍确保任何技能都满足最基础的两个字段检查。在团队环境里这个校验可以放到持续集成流程中配合 frontmatter 的格式解析比如用 yq 或 python 的 yaml 模块来解析和校验字段类型把质量门槛自动化。6.4 我自己的使用习惯与一点建议最后聊一点个人经验。我现在的日常是所有技能只在 ~/ai-skills 里维护每周集中花十分钟更新社区内容和自己的新需求新增一个技能只需要四个动作建目录、写 SKILL.md、跑 sync 脚本、开新会话验证。这套流程跑顺之后我几乎没有再在两个 Agent 之间手动搬运过技能文件。如果你刚开始改造我的建议是不要追求一步到位。先挑两三个最常用的技能做试点把 frontmatter 模板定好、链接脚本跑通确认两边都能正常触发后再把其余技能批量迁移。一次性迁移二三十个技能一旦某个文件的格式不兼容排查成本会直接把你劝退。从两三个开始逐步扩大才是收益最高、风险最低的节奏。
一套Skills多Agent共享：Claude Code与Codex统一管理实战方案
如果你同时在用 Claude Code 和 Codex而且已经往技能清单里塞了两位数以上的 Skill大概率经历过我上个月那种崩溃一个刚改好的 code-review 技能Claude Code 这边用的是新规则Codex 那边还在跑旧版本社区里看到一份不错的前端开发 skills 合集下载解压之后发现目录结构两边不通用更烦的是给每个工具各维护一份文件每次更新都要想这次同步过去没有。我当时在十几个 skill 文件里来回复制粘贴了二十多回实在受不了于是专门做了一套统一管理方案把全部 Skill 的源文件收敛到一个 Git 仓库通过符号链接和同步脚本挂载到 Claude Code 和 Codex 各自的 skills 目录实现一套 Skills 在多个 Agent 之间共享。这套结构我用了近两个月中间踩了不少坑今天把整个方案和排查过程完整写出来给同样被多 Agent 技能管理折磨的人一个可直接照抄的答案。1. 为什么坚持一套 Skills多 Agent 共享各自为战的代价很多人的最初状态就是各放各的Claude Code 的 skill 放~/.claude/skills/Codex 的 skill 放~/.codex/skills/两边井水不犯河水看似没什么毛病。但只要你认真用了两个 Agent并且技能数量开始增加各放各的会在三个层面同时拖后腿。1.1 双份维护带来的内容漂移我吃过最直接的亏是规则不统一。上上个月我想让两个 Agent 在代码审查时都遵守一套新的安全检测规则于是先改了 Claude Code 里的 code-review 技能把必须检查密钥硬编码、SQL 拼接、反序列化入口这几条加了进去当时想着回头再改 Codex 那边的文件结果连着两天忙别的完全忘了。后来在 Codex 里跑了一次 review它给的检查清单还是老的漏掉了新加的密钥检测项。这不是 Codex 不行是我根本没把最新规则同步过去。这种问题在一个人同时维护两份文件时几乎无法避免因为你多一次复制粘贴就多一次版本不一致的机会。更隐蔽的是 YAML frontmatter 的字段差异。两个工具对 skill 元数据的解析策略不完全一样同一个 frontmatter 里多写一个不认识的字段Claude Code 可能只是忽略而 Codex 可能整个文件解析失败反过来也一样。手动复制文件的时候很容易顺手把上一份文件里为另一个工具调整过的字段一起带过去结果一边能跑一边直接不识别调试半天才发现是字段兼容问题。1.2 没有版本概念等于没有后悔药手动复制意味着你几乎没有版本管理昨天改的 html2md 技能到底改到哪个文件了今天想回退到三天前能用的版本完全无从下手。虽然两个工具各自的 skills 目录本质也是磁盘上的普通文件但大家维护的时候几乎不会想到去 git init。技能文件这种需要频繁迭代的内容没有 git 历史保护一旦改坏就要靠记忆手修效率极低。等到技能数量涨到二十几个回滚一个坏掉的技能几乎等于重写一遍。1.3 统一管理方案要解决的三件事所以我在设计这套一套 Skills多 Agent 共享方案时给自己定了三个硬指标单一事实源所有 skill 的源文件只在一个目录里维护这个目录本身就是 git 仓库目录外的文件都不允许作为可修改副本存在。一致加载路径通过符号链接和同步脚本把源目录映射到不同 Agent 各自约定的技能加载目录agent 扫描时看到的仍是标准结构但实际指向同一份源文件。可回滚可审计所有变更走 git每个 skill 每次调整都有 commit 记录出问题直接git revert。这三个指标看起来简单真做起来牵扯的细节不少。下面先把两个工具的技能机制讲明白不然链接建得再漂亮格式不兼容还是白搭。2. 先摸清两家底细Claude Code 与 Codex 的 Skills 机制差异很多人以为既然都有 skills 目录那就复用了真这么干会立刻翻车。两个 Agent 的 skills 机制在目录位置、元数据解析、触发策略上都有差别共享的前提是先把这些差异理清。2.1 Claude Code 的 Skills目录约定与自动触发Claude Code 的技能体系目前是用户级与项目级两层。用户级目录是~/.claude/skills/项目级目录是项目下的.claude/skills/每个技能独立建一个子目录子目录里面必须有一个SKILL.md文件这个文件顶部是 YAML frontmatter下面是 Markdown 正文。Claude Code 在会话启动时或需要时会扫描可用的技能读取每个 SKILL.md 的 frontmatter 中的 name 和 description把这些元数据作为候选能力表交给模型当模型判断当前任务与某个 description 匹配时就会把对应 SKILL.md 正文加载进上下文来指导执行。所以 description 写得好不好直接决定技能会不会被正确触发。如果 description 写得太宽泛模型大概率不会在真正需要时想起来调用如果写得太窄又会错过相似任务的触发机会。2.2 Codex 的 Skills与 AGENTS.md 并存的能力体系Codex 这边的机制和 Claude Code 相似但不一样。它之前主要依赖项目里的 AGENTS.md 作为全局指导文件后来也引入了独立技能目录默认在~/.codex/skills/下同样以 SKILL.md 文件为技能入口。不同版本的 Codex 对这个功能的支持程度有差异有的版本还提供codex skills add之类的子命令来注册技能。我本机上观察到的行为是Codex 会扫描技能目录里的 SKILL.md解析 frontmatter再根据用户任务的语义决定是否调用对应技能。需要特别提醒的是Codex 的版本迭代很快不同小版本对 skills 目录的扫描策略可能有差异。所以做统一管理前先执行codex --version确认手上的版本再看一眼codex skills --help的输出确认支持哪些参数。不要照搬网上三个月前的教程命令格式很可能已经变了。顺带回答一个被问得比较多的问题harness 和 agent 有什么区别。简单说harness 是 Agent 运行的执行框架负责工具调度、会话管理、命令分发agent 是模型本身加上下文、加技能后的产物。skills 是给 agent 加能力包的手段和 harness 不在同一个层面所以别把它们混为一谈。2.3 两边差异对照表为了直观我把目前我机器上两个工具的实际差异整理成了一张表对比项Claude CodeCodex用户级技能目录~/.claude/skills/~/.codex/skills/项目级技能目录.claude/skills/项目内可通过 AGENTS.md 引用技能本体通常在用户级目录技能文件SKILL.mdSKILL.md元数据YAML frontmattername、description 等同样使用 YAML frontmatter但兼容字段集合更小触发方式按 description 语义匹配 手动触发按 description 语义匹配自定义脚本支持在 SKILL.md 里引用同目录脚本可引用但路径解析方式可能不同这张表的核心结论是两者没有本质冲突都认 SKILL.md 和 YAML frontmatter这给了一套 Skills 两处引用的实现基础但元数据字段的兼容范围不一样这就要求我们写 frontmatter 时只保留两边都认的最小公共字段而不是把某一方特有的扩展字段写进去。3. 统一管理核心方案一个 Git 仓库 符号链接打通既然两边的目录位置不同但文件格式大体兼容最直觉的做法就是让多个目录都指向同一份源文件。我采用的方式是一个统一仓库 一组符号链接 一个同步脚本。3.1 仓库目录规划我建议在用户主目录下建一个专门的 ai-skills 目录并把它初始化为 git 仓库mkdir -p ~/ai-skills cd ~/ai-skills git init仓库内部按一个技能一个子目录组织~/ai-skills/ README.md code-review/ SKILL.md scripts/ review-rules.json frontend-dev/ SKILL.md templates/ component.stub.tsx html2md/ SKILL.md academic-research/ SKILL.md每个子目录都包含一个 SKILL.md这是被 Agent 扫描的入口同目录下可以放这个技能依赖的脚本、模板、数据文件Agent 在执行时按相对路径引用它们。比如 frontend-dev 里的模板文件就是让 Agent 在生成组件时照着模板结构来。为什么不用一个扁平的大 SKILL.md 把所有技能塞进去因为两个 Agent 的扫描器都要求一个技能一个目录塞在一起会被当成一个整体扫描命名和触发都会混乱。保持目录粒度和 Agent 的内部模型一致迁移成本最低。3.2 用符号链接打通两个 skills 目录统一仓库建好之后关键一步是在 Claude Code 和 Codex 的 skills 目录里建立链接。符号链接的意思是~/.claude/skills/code-review这个路径本身不是实体目录而是一个指向~/ai-skills/code-review的快捷方式。Agent 扫描时打开这个路径看到的是源目录里的内容我们修改源目录里的 SKILL.md所有链接点立即生效不需要同步、不需要拷贝。先确保两边的用户级 skills 目录存在mkdir -p ~/.claude/skills ~/.codex/skills然后手动为第一个技能建立链接尝试验证ln -s ~/ai-skills/code-review ~/.claude/skills/code-review ln -s ~/ai-skills/code-review ~/.codex/skills/code-review验证一下链接是否有效ls -la ~/.claude/skills/code-review cat ~/.claude/skills/code-review/SKILL.md如果 cat 能看到内容说明 Agent 也能读。接下来为仓库里所有技能批量建立链接就轮到同步脚本上场了。3.3 同步脚本 sync-skills.sh一个可复制的批次脚本遍历统一仓库下的每个子目录检查是否存在 SKILL.md存在就在两个目标目录里建立链接#!/usr/bin/env bash set -euo pipefail SOURCE_DIR$HOME/ai-skills CLAUDE_SKILLS$HOME/.claude/skills CODEX_SKILLS$HOME/.codex/skills mkdir -p $CLAUDE_SKILLS $CODEX_SKILLS for skill_dir in $SOURCE_DIR/*/; do name$(basename $skill_dir) if [ ! -f $skill_dir/SKILL.md ]; then echo skip: $name (no SKILL.md) continue fi ln -sfn $SOURCE_DIR/$name $CLAUDE_SKILLS/$name ln -sfn $SOURCE_DIR/$name $CODEX_SKILLS/$name echo linked: $name - $SOURCE_DIR/$name done echo sync done.脚本的逻辑不复杂但有几个关键点要解释。set -euo pipefail是为了在出错时快速失败避免执行一半还继续往下跑。ln -sfn中的-f强制覆盖已存在的链接-n防止把目标目录当链接目标继续层层嵌套这两个参数组合在重复执行脚本时尤其重要。for skill_dir in $SOURCE_DIR/*/只遍历目录自动跳过根目录下的 README.md 等普通文件。把这个脚本放在~/ai-skills/sync-skills.sh加可执行权限chmod x ~/ai-skills/sync-skills.sh ~/ai-skills/sync-skills.sh之后每次在仓库里新增或删除技能只要重新跑一遍脚本两个 Agent 的目录就会同步到最新状态。Windows 用户的话符号链接需要用mklink /D创建并且需要开发者模式或管理员权限PowerShell 脚本逻辑类似但ln换成New-Item -ItemType SymbolicLink。要注意的是Windows 下 git clone 一个带符号链接的仓库时默认不一定保留链接语义设置git config core.symlinks true才能保证签出的仓库里链接仍然有效。如果嫌麻烦Windows 上直接退化为复制脚本 增量同步也是可行的后面踩坑部分会详细对比。4. 让一份 Skill 同时兼容两个 Agent模板、frontmatter 与入口配置链接是搭好了但技能内容本身如果只适配某一边一旦被另一个 Agent 加载轻则不生效重则报错。所以统一管理方案里最重要的一环是写一份两边都兼容的 SKILL.md 规范。4.1 统一 frontmatter 模板我目前所有技能用的 frontmatter 模板是--- name: code-review description: 当用户要求审查代码质量、定位潜在 Bug、检查安全漏洞或提交 PR 审查意见时使用。输入是代码片段或 diff输出是分条列出问题等级、风险点和具体修改建议。 ---这段 frontmatter 里我只用了两个字段name 和 description。这是两个 Agent 都认的核心字段。不要往里塞 only-tools、metadata 之类只在某一方文档里出现的扩展字段因为共享仓库一旦被另一方读取解析器遇到不认识的字段可能直接失败。你想加自定义信息放到正文里比放到 frontmatter 里安全得多。name 的命名规范建议统一用小写字母加短横线比如 frontend-dev、code-review不要用空格和中文。虽然部分 Agent 可能容忍中文名但链接路径、脚本引用、命令行调用都会遇到麻烦没必要冒险。description 的写法必须覆盖什么任务用、输入是什么、输出是什么。两个 Agent 读取 description 时通常会把整段文本送去模型做语义匹配所以描述不要写成关键词堆砌要写成完整的句子组合让模型能准确理解触发边界。4.2 正文结构的统一约定SKILL.md 的正文部分我按固定结构组织这样每个技能看起来都一样Agent 处理起来也更稳定适用场景与触发条件用几行明确说明什么时候该用这个技能什么时候不该用。核心执行步骤用数字编号列出 3 到 10 步一步步告诉模型怎么做。参考命令与示例给出可直接执行的命令或调用示例尽量贴实际。已知限制与常见坑把容易出错的地方写清楚能显著减少 Agent 的试错。这里有个重要经验SKILL.md 不需要写得很长我一般控制在 150 行以内。原因是技能被触发后正文内容会被加载进模型上下文占的是宝贵的 token 配额。写得太多技能还没发挥作用上下文先被挤爆了。把核心步骤和关键限制写清楚剩下的让模型用它的知识补全反而是更高效的用法。我早期吃过一个亏在某技能里把整个工具的使用手册都拷了进去约四百行结果每一次触发都会多消耗几千 token会话上下文很快见底。后来把冗余示例全部精简只留下最关键的部分效果反而更好。4.3 CLAUDE.md 与 AGENTS.md 的配合使用除了 SKILL.md 本身两个 Agent 还会各自读取项目级或全局的指导文件Claude Code 认 CLAUDE.mdCodex 认 AGENTS.md。这两个文件不是技能但它们承担着告诉 Agent 去哪找技能、什么时候该用技能的任务。我的做法是在每个项目根目录维护一份极简的 CLAUDE.md 和 AGENTS.md里面都会写一段固定的技能索引## Available Skills - code-review: 提交 PR 前必须执行代码审查 - frontend-dev: 涉及 React 组件开发时使用同时在用户级全局位置也放一份指向常用技能的说明。这样即使 SKILL.md 的 description 在某个场景下让模型犹豫不决项目级指导文件也能直接把模型引导到目标技能。两个文件内容保持一致配合统一仓库的符号链接整个技能体系才算完整接通。5. 容易翻车的几个地方切换端点失败、链接失效与扫描缓存统一管理方案跑顺之后真正令人头疼的反而不是方案本身而是各种环境细节。这一节我把实际使用中最容易翻车的几个问题展开讲包括排查思路而不是直接给结论。5.1 cc-switch 切换本地端点失败的排查思路有不少人在切换 Codex 的 endpoint 配置时遇到过类似 cc switch local endpoint failed while handling codex endpoint /responses 的报错网上对应的讨论也不少。这个报错看着吓人其实绝大多数情况跟你的技能仓库没关系而是切换工具在修改本地配置时出了偏差。我排查这类问题一般按这个顺序走看配置内容。cc-switch 这类工具本质上是帮你改 Agent 的配置文件、切换不同的 API 供应商或端点。先打开它生成的配置文件核对目标端点的 baseURL、模型名、密钥字段是否都写对了。很多时候是切换时少了一项配置导致 Agent 在访问 /responses 路径时拿不到合法响应。确认目标服务是否真的在监听。如果是连本地服务先用命令确认端口和进程状态例如lsof -i :端口号或者netstat -ano | findstr 端口号如果服务没起来切过去自然报 failed。看日志。切换工具一般会在用户目录下留日志文件翻最后几十行错误原因通常会写得比界面里更直白。兜底办法直接绕过切换工具手工编辑 Agent 自己的配置文件把 baseURL 和 API 密钥写上然后重启会话看问题是否消失。补充一句/responses 是某些端点协议里的标准请求路径如果你看到 failed while handling 这个位置说明请求已经发出去了只是处理环节挂掉了跟技能文件本身完全没有关系不用去怀疑刚才建的符号链接。5.2 符号链接在同步盘和权限条件下失效符号链接方案最大的敌人是各种同步工具。我一开始把 ~/ai-skills 仓库放在 iCloud Drive 同步目录下结果发现 iCloud 对符号链接的支持非常不友好它要么不识别链接要么把链接当成普通文件处理最终导致 ~/.claude/skills/code-review 变成一个悬空链接Agent 扫描时直接跳过。这个问题的根源是你的源目录和链接目录分别处于不同的同步层级里云同步的冲突解决策略没法理解快捷方式这种概念。所以我的建议是如果要用符号链接源仓库务必放在本地非同步目录比如 ~/ai-skills不要放在 iCloud、OneDrive、企业网盘等会做文件同步的目录目标 skills 目录也要在本地。权限方面还有一个容易忽略的点如果 ~/.claude 或 ~/.codex 目录属于 root 或者别的用户ln -sfn会失败。用ls -ld检查两个目录的所有者不对就先 chown 回来。我自己在服务器上用普通用户跑 Codex 时就遇到过这种情况目录是容器挂载出来的所有者对不上排查了半天。5.3 Agent 扫描缓存与新技能不生效一个非常容易误解的问题是我刚建好链接立刻去命令行里让 Agent 用新技能结果它完全没有反应。这不是链接建错了而是 Agent 的技能扫描发生在会话启动阶段或特定时机。Claude Code 和 Codex 通常会在启动新会话时读取技能列表你开着旧会话追加提问它可能不会重新扫描技能目录。正确的验证方式是开一个全新的会话先直接问你有哪些可用技能看输出里有没有包含刚加的那个技能没有的话再检查链接和 frontmatter。另一个技巧是先用命令行手动触发技能确认技能本身可用再考察自动语义匹配是否触发。Windows 下还有一个坑mklink /D创建的是目录符号链接但如果你用普通用户权限执行会提示权限不足需要先开启开发者模式或者用管理员权限的终端执行。另外 git 在 Windows 上默认不开启符号链接支持把仓库 clone 到 Windows 机器时链接可能变成普通文本文件需要在 git config 里设置 core.symlinks true并且使用支持符号链接的文件系统。6. 进阶玩法版本管理、团队协作与 Skill 质量检查基础方案跑通后统一管理能带来的收益其实远不止两个 Agent 用同一份文件这么简单。很多衍生价值是在使用过程中慢慢被放大的。6.1 把社区热门技能包管起来我身边不少人会下一些社区里很火的技能合集比如那套叫 superpower skills 的系列涵盖了很多任务拆解和自动化执行的技巧还有专门针对前端开发、渗透测试、学术研究等不同方向的 skills 包。把这些外部技能纳入统一仓库时我建议不要直接整个目录拷进来就完事而是先想清楚维护关系。如果上游更新很频繁且你不需要改动内容可以用 git submodule 把它挂在 ai-skills 仓库下每次git submodule update就能拉最新版如果上游更新不活跃或者你已经对内容做了大量本地化改造就直接复制进仓库完全接管后续维护。核心原则是不要让一份代码有两个维护入口。我在管理前端开发 skill 包时就是先复制后改造因为社区模板里很多组件格式跟我的项目习惯不一致改完之后再挂到两个 Agent 上使用效果比原版好很多。6.2 多台机器自动同步如果你像我一样有办公电脑、笔记本和服务器三个环境统一仓库只有一份但源文件要出现在所有机器的本地磁盘上链接才有意义。最简单的做法是在每台机器上都 clone 一遍 ai-skills 仓库然后跑一次 sync-skills.sh。手动操作虽然可行但偶尔会漏。我后来用一个 cron 任务来自动化这一步*/15 * * * * cd ~/ai-skills git pull --ff-only /dev/null 21 ~/ai-skills/sync-skills.sh /dev/null 21每 15 分钟检查一次仓库远程更新有则拉取然后重建所有链接。注意多台机器协作时配置文件里的密钥和敏感信息不要放进 ai-skills 仓库仓库里只放技能内容涉及个人密钥的地方用环境变量引用避免把明文带进 git 历史。6.3 给技能仓库加一道质量检查技能数量超过二十个之后光靠肉眼检查 frontmatter 已经不可靠了。我在仓库里放了一个很小的校验脚本 skill-lint.sh逻辑并不复杂#!/usr/bin/env bash for skill_dir in ~/ai-skills/*/; do name$(basename $skill_dir) file$skill_dir/SKILL.md [ -f $file ] || { echo error: $name missing SKILL.md; exit 1; } grep -q ^name: $file || { echo error: $name no name field; exit 1; } grep -q ^description: $file || { echo error: $name no description field; exit 1; } echo ok: $name done我还会在每次 git commit 之前跑一遍确保任何技能都满足最基础的两个字段检查。在团队环境里这个校验可以放到持续集成流程中配合 frontmatter 的格式解析比如用 yq 或 python 的 yaml 模块来解析和校验字段类型把质量门槛自动化。6.4 我自己的使用习惯与一点建议最后聊一点个人经验。我现在的日常是所有技能只在 ~/ai-skills 里维护每周集中花十分钟更新社区内容和自己的新需求新增一个技能只需要四个动作建目录、写 SKILL.md、跑 sync 脚本、开新会话验证。这套流程跑顺之后我几乎没有再在两个 Agent 之间手动搬运过技能文件。如果你刚开始改造我的建议是不要追求一步到位。先挑两三个最常用的技能做试点把 frontmatter 模板定好、链接脚本跑通确认两边都能正常触发后再把其余技能批量迁移。一次性迁移二三十个技能一旦某个文件的格式不兼容排查成本会直接把你劝退。从两三个开始逐步扩大才是收益最高、风险最低的节奏。
