1. 先搞清楚一件事为什么Skills需要“统一管理”用过 Claude Code 或 Codex 一段时间的人大概率都会遇到同一个尴尬局面昨天在某台电脑上配好的技能包今天换到另一台设备或者换个 Agent 工具就失灵了。这里说的 Skills其实指的就是 Agent 的能力扩展包。你可以把每个 Skill 理解成一个“技能模块”——里面通常包含一条 SKILL.md 作为使用说明再加上若干脚本、模板、参考文档。Agent 在执行任务时会去读取这些能力定义根据任务类型调用对应的技能。比如“前端开发 skills”就是让 Agent 具备快速生成页面骨架、拆组件、写样式的能力“学术研究 skills”则是帮 Agent 学会检索文献、整理摘要、格式化引用。问题在于Claude Code 和 Codex 虽然都支持 Skills但它们的目录规范、加载机制、优先级规则之间是有差异的。如果你只是简单地复制粘贴很快会发现Codex 能识别的技能Claude Code 不一定读得到同一份技能配置在两个工具里的执行结果可能截然不同团队里每个人都自己配一份不仅重复劳动还会版本失控。于是就有了这篇文章的出发点能不能用一套 Skills同时喂给 Claude Code 和 Codex让它们通过同一套技能库来干活先把结论放在前面可以而且并不需要写多复杂的代码。核心思路就是“统一目录 软链接 / 同步脚本 两套适配层”。下面我把这套方案从原理到落地完整拆开讲。2. 从官方规范看 Claude Code 与 Codex 的 Skills 差异要设计统一方案第一步是搞清楚两个工具各自是怎么加载 Skills 的。这一步不能跳过因为很多人在统一管理时踩坑就是因为没有理解底层机制。2.1 Claude Code 的 Skills 规范Claude Code 对 Skills 的官方定义比较清晰一个 Skill 就是一个文件夹里面必须包含 SKILL.md 文件文件名必须大写、不能改。SKILL.md 的开头需要写 YAML frontmatter比如 name 和 description 字段接下来的正文部分则是具体的指令说明、使用步骤、注意事项等。我实际用下来Claude Code 加载 Skills 的路径优先级大致是这样项目级.claude/skills/目录这是最常用的方式适合把技能跟某个项目绑定用户级~/.claude/skills/目录适合放一些全局通用的技能比如“代码审查”这类任何项目都用得上的能力。Claude Code 的特点是它会根据 SKILL.md 里的 description 字段结合当前会话的上下文自行决定“要不要调用某一个技能”。这意味着你不需要显式点名它会在合适的时候主动加载。这个机制很智能但也带来一个问题如果 description 写得模糊它可能在不需要的时候触发影响响应质量和效率。2.2 Codex 的 Skills 规范Codex 这边的规范跟 Claude Code 相似但不完全相同。Codex 同样使用 Markdown 文件来描述技能但它的目录结构和加载机制有自己的体系。Codex 支持从几个位置加载技能包括项目级目录和用户级目录具体路径在不同版本上有调整。Codex 的特点是它更偏向于显式调用。你可以在对话里直接要求它“使用某个技能”它会更明确地按技能文件中的步骤去执行。这种“显式优先”的设计思路好处是可控性强坏处是如果技能文件里没有写清楚触发条件它可能完全忽略这个技能。2.3 差异总结与统一化的基础为了让你一眼看明白我把核心差异整理成一张表对比维度Claude CodeCodex技能描述文件SKILL.md大写必须是这个文件名支持 Markdown 描述文件名可自定义目录位置.claude/skills/或~/.claude/skills/项目级与用户级路径但结构与 Claude 不同加载方式根据 description 自动触发更偏向显式调用Frontmatter 要求有明确规范name、description灵活但建议尽量兼容多文件支持支持引用脚本、模板等相对路径同样支持我的结论是既然两边都认可“Markdown 描述技能 附带资源文件”这种基本模式那统一方案的关键就不在于重写所有技能而在于“翻译”两边的加载规范——保留一份核心技能源文件再为不同工具生成对应的描述入口。3. 整体方案单源技能库 双端适配统一管理不做“双份维护”而是建立一个单一技能源目录再通过自动化手段把技能分发到 Claude Code 和 Codex 各自期望的位置。这样改技能只改一处两个 Agent 都能同步生效。3.1 目录结构设计建议的目录结构是这样agent-skills/ ├── skills/ # 唯一技能源真正的“一套Skills”放在这里 │ ├── frontend-dev/ │ │ ├── SKILL.md # 统一的技能描述 │ │ ├── templates/ │ │ └── scripts/ │ ├── code-review/ │ │ ├── SKILL.md │ │ └── rules/ │ └── research-assistant/ │ ├── SKILL.md │ └── prompts/ ├── adapters/ │ ├── install_claude.sh # 分发到 Claude Code 的脚本 │ ├── install_codex.sh # 分发到 Codex 的脚本 │ └── sync_all.sh # 一键同步 └── README.md所有技能文件都以 Claude Code 的规范为主来编写每个技能是一个目录内部必须有 SKILL.md。之所以以 Claude Code 规范为主是因为它对 frontmatter 的要求更严格而 Codex 对这类格式的容忍度相对高。以严格的为主兼容性更好。3.2 分发策略复制还是软链接在同步时有两种思路复制文件或者创建软链接。复制方案更稳妥。因为 Claude Code 和 Codex 在读取技能时可能会有缓存机制软链接一旦指向失效工具会静默跳过甚至报错。但复制会带来一个问题技能源文件更新后需要重新执行分发脚本否则两边不同步。软链接方案更优雅。只要源目录保留在固定位置软链接能保证两端始终读到最新内容不需要反复同步。缺点是如果你换设备、换目录或者源目录被清理所有软链接会一起失效。我的建议是个人使用如果你能保证目录稳定首选软链接团队协作或者目录结构频繁变化选择复制 同步脚本虽然多一步操作但故障率更低。3.3 各端适配要点Claude Code 的适配相对简单因为技能源就直接按它的规范组织。你只需要在~/.claude/skills/下为每个技能建立软链接或复制目录即可。Codex 的适配要稍微花点心思。Codex 的加载机制要求其技能路径下存在可被扫描的 Markdown 描述文件但文件名不一定要求是 SKILL.md。为了保持两端一致我仍然保留这个文件名实测下来 Codex 能正常识别。需要注意的一点是如果 Codex 版本较新建议在同步后重启会话否则它可能还停留在旧缓存里。4. 实操从零开始搭一套可用的共享技能库方案听起来不复杂但落地过程中处处是细节。我建议你跟着下面的步骤走一遍每一步我会说明操作原因和常见坑。4.1 准备基础环境在动手之前确认以下事项已安装并正常登录 Claude Code 客户端已安装 Codex 客户端且能正常发起会话终端环境支持 bash 脚本Windows 用户建议用 Git Bash 或 WSL。这里有一个很容易被忽略的点如果你之前手动给 Claude Code 或 Codex 配过技能先把它们各自的技能目录清空或者备份避免新旧叠加造成冲突。很多人在同步后发现“技能没生效”八成就是新旧版本在打架。4.2 创建技能源以一个“前端开发”技能为例我先示范创建一个“前端开发 skills”风格的技能。这个技能的目标是当 Agent 被要求生成一个前端页面时它能够参照给定的项目结构、设计规范和组件模板来输出代码。进入agent-skills/skills/frontend-dev/目录创建 SKILL.md--- name: frontend-dev description: 用于快速生成标准化的前端页面和组件代码。当需要创建网页界面、React/Vue组件、响应式布局或前端项目脚手架时使用。 --- # Frontend Development Skill ## 适用场景 - 从零创建一个前端页面 - 将设计稿转换为 HTML/CSS 代码 - 生成 React 或 Vue 组件 - 搭建项目基础文件结构 ## 执行步骤 1. 确认目标框架和技术栈。默认使用 React TypeScript如用户指定则遵循用户要求。 2. 参考 templates/ 目录下的组件模板和页面模板。 3. 生成的代码结构必须包含组件文件、样式文件、类型定义文件。 4. 遵循 design-tokens.md 中的颜色、间距、字号规范。 5. 在输出结束时用简短说明列出所有生成的文件及其用途。 ## 重要注意事项 - 页面必须适配移动端最小宽度按 375px 设计。 - 禁止在未征得用户同意的情况下引入 UI 组件库。 - 生成的组件必须包含基础注释说明 props 的含义。在这个技能目录下你还可以放templates/目录里面存一个Component.tsx.template基础模板以及一个design-tokens.md说明设计规范。Agent 在加载技能后会按描述中的指引去读取这些文件。4.3 编写分发脚本接下来写分发脚本这是整个方案的核心。先写adapters/install_claude.sh#!/usr/bin/env bash # 分发 skills 到 Claude Code 用户级目录 set -euo pipefail SOURCE_DIR$(cd $(dirname $0)/../skills pwd) CLAUDE_SKILLS_DIR$HOME/.claude/skills mkdir -p $CLAUDE_SKILLS_DIR for skill_dir in $SOURCE_DIR/*/; do skill_name$(basename $skill_dir) # 清理旧链接或旧目录 rm -rf $CLAUDE_SKILLS_DIR/$skill_name # 建立软链接 ln -s $skill_dir $CLAUDE_SKILLS_DIR/$skill_name echo Claude Code: linked $skill_name done再写adapters/install_codex.sh#!/usr/bin/env bash # 分发 skills 到 Codex 用户级目录 set -euo pipefail SOURCE_DIR$(cd $(dirname $0)/../skills pwd) CODEX_SKILLS_DIR$HOME/.codex/skills mkdir -p $CODEX_SKILLS_DIR for skill_dir in $SOURCE_DIR/*/; do skill_name$(basename $skill_dir) rm -rf $CODEX_SKILLS_DIR/$skill_name ln -s $skill_dir $CODEX_SKILLS_DIR/$skill_name echo Codex: linked $skill_name done最后写一个sync_all.sh把两个脚本串起来#!/usr/bin/env bash set -euo pipefail SCRIPT_DIR$(cd $(dirname $0) pwd) bash $SCRIPT_DIR/install_claude.sh bash $SCRIPT_DIR/install_codex.sh echo All skills synced.给脚本加执行权限chmod x adapters/*.sh4.4 首次执行与验证执行一键同步cd agent-skills ./adapters/sync_all.sh正常输出类似Claude Code: linked frontend-dev Claude Code: linked code-review Codex: linked frontend-dev Codex: linked code-review All skills synced.接下来分别去两个工具里验证。在 Claude Code 中直接问它“请用 frontend-dev 技能帮我生成一个简单的商品卡片组件。”如果响应中出现了“我将使用前端开发技能”或类似的引用说明说明技能被正确加载。在 Codex 中用更明确的指令“use the frontend-dev skill to generate a product card component”。Codex 更吃显式指令这一句话能快速验证技能是否生效。4.5 一个非常容易踩的坑Frontmatter 的 description 长度我遇到过最多的问题就是 Claude Code 读不到技能。排查到最后发现是 SKILL.md 里的 description 写得太短像“用于前端开发”这种一句话描述被 Claude Code 的自动触发机制直接忽略了。Claude Code 判断是否启用技能高度依赖 description 的内容质量。建议描述里写清楚“什么场景下用、解决什么问题、大概怎么做”长度最好在 100-200 个字符之间太短触发不准太长可能被截断。5. 版本管理从一门手艺变成一套工程技能一旦多起来就必须做版本管理。推荐把整个agent-skills目录放到 Git 仓库里这是投入产出比最高的一个动作。5.1 仓库组织方式git 仓库的根目录就放在agent-skills/下。skills/目录是核心资产adapters/是分发工具README.md里写清楚每个技能是做什么的、适合什么场景。具体操作cd agent-skills git init git add . git commit -m 初始化技能库frontend-dev、code-review、research-assistant之后每次修改技能都走标准的 Git 流程。建议技能描述文件使用“变更描述 影响范围”的提交信息比如“调整 frontend-dev 的组件模板增加暗色模式变量”。5.2 团队协作的额外建议如果是团队共用一套技能库我建议再增加两层第一引入一个skills/README.md以表格形式维护技能清单。列出技能名称、适用 Agent、维护人、最近更新日期。这个文件看起来很“文档化”但在多人协作时极其有用。第二对技能变更做简单的评审机制。不需要很强的流程但至少要求“改完技能后必须在 Claude Code 和 Codex 里各跑一次验证”。这一步能拦截掉大量低级错误。我见过不少团队技能库建起来了但两三个人同时改同一份技能文件冲突不断。后来给每个技能目录加了一个 OWNER 标记改动前先确认维护人问题就少了很多。5.3 关于“内置 skills”与“第三方 skills”的混用现在网上有不少公开的“skills 集合”项目比如号称“XX skills”的各种仓库。这些第三方的技能质量参差不齐有的确实能提升 Agent 的表现有的就是堆砌关键词、几乎没有实际效果。我的做法是先人工审查再纳入技能库。审查的重点不是代码多漂亮而是指令是否具体、步骤是否可执行、有没有恶意代码。特别是涉及“让 Agent 执行系统命令”的技能要格外小心。技能文件本质上是给 Agent 的指令别人写的技能你直接套用等于让 Agent 按陌生人的指示干活风险不可忽视。6. 性能与副作用不要为了让 Agent “变强”而拖垮它这里我想说一个很多教程不会提的话题技能不是越多越好。6.1 自动触发机制带来的“技能膨胀”问题Claude Code 的自动触发机制决定了它会扫描所有可用技能的 description再决定是否启用。如果技能库里堆了 100 个技能其中 80 个跟当前任务无关这 80 个 description 依然会影响模型的判断。我会将它理解为一种注意力资源消耗。我的实测感受是技能数量控制在 10-20 个之间比较合适。超过 30 个之后技能的触发质量会下降偶尔还会出现“答非所问”——Agent 强行套用不相关技能的场景。所以统一管理并不是简单地把所有技能都塞进共享目录而是要定期梳理剔除那些不再使用或功能重叠的技能。保留一个“高质量、小而精”的技能库实际效果远好于一个大而全的仓库。6.2 软链接失效的排查在跨设备同步时软链接风险最明显。比如把技能库放在云盘同步目录换到另一台电脑后云盘可能把软链接同步成普通文本导致技能加载失败。如果你遇到“技能明明存在但 Agent 就是不认”先检查软链接是否有效ls -la ~/.claude/skills/frontend-dev如果输出末尾有-指向具体的源目录说明链接正常如果显示为普通目录或断链就要删掉重新同步。为了降低这种风险我给团队的建议是固定技能库的存放路径比如统一放在~/dev/agent-skills不随意变动目录位置。路径稳定软链接才能稳定。6.3 双工具行为不一致的处理同一套技能Claude Code 和 Codex 的表现完全一致几乎是不可能的。原因很简单两个工具底层模型不同对指令的理解和执行习惯也不同。比如同一个“code-review”技能Claude Code 可能会逐行检查并提出修改建议而 Codex 可能更倾向于给出整体评价和风险点。这些差异不是 bug也不是技能文件写错了而是模型本身的风格差异。如果你的目标是“两个工具输出尽量一致”唯一的办法是在技能描述里写得更细、更结构化减少模型自行发挥的空间。比如在“执行步骤”里逐条列出必须检查的项规定输出格式。当“发挥空间”被压缩输出的一致性会明显提升。7. 先把一套技能跑通再追求规模最后分享一点我在实际使用中的体会。统一管理这一套方案听起来很“工程化”好像必须一上来就把所有技能梳理成一个庞大体系。但我的建议恰恰相反先用两三个核心技能跑通全流程验证方案可用再逐步扩展。第一次就塞二十个技能你会花大量时间排查冲突和路径问题反而打击积极性。从“一个前端开发技能同时被 Claude Code 和 Codex 识别”这个小目标开始。当这件事稳定运行一周以上你自然会发现哪些技能值得加入、哪些技能应该在源目录下被删除或合并。另外这套方案不只适用于 Claude Code 和 Codex。未来如果出现新的 Agent 工具只要它也支持基于 Markdown 的技能描述你完全可以沿用“单源技能库 多端分发”的思路在 adapters 目录下再加一个安装脚本就行。基础设施搭好之后扩展新工具的成本很低这才是统一管理最大的复利。
