Claude Code 与 Codex 共享 Skills 配置教程
本教程将指导你如何让 Claude Code 和 Codex 这两个 AI 编程 Agent，共享和调用同一套 Skill（技能）文件，实现“一次定义，多处使用”。
适用场景
- 你已搭建好 Claude Code 的 Skill 体系（如“一人公司”架构）
- 你希望在 Claude Code 不可用时（如 Token 额度耗尽），由 Codex 作为备用驱动引擎继续工作
- 你希望统一管理 Skill，避免在两个工具间重复维护
核心原理
- 统一标准：Claude Code 和 Codex 都遵循 Agent Skills 开放标准，即使用
SKILL.md文件定义技能。 - 统一路径：通过符号链接 (Symlink)，让两个工具指向同一份
SKILL.md文件，实现“一处存放，多处调用”。
操作步骤
第一步：确定技能库的唯一存放位置
选择一个目录作为你的“总技能库”，例如：
mkdir -p ~/shared-agent-skills
将所有 SKILL.md 文件按功能放入该目录，每个技能一个子文件夹：
~/shared-agent-skills/
├── code-review/
│ └── SKILL.md
├── generate-commit/
│ └── SKILL.md
└── debug-api/
└── SKILL.md
第二步：为 Claude Code 创建符号链接
Claude Code 会扫描以下目录来发现 Skill：
- 项目级：
<项目根目录>/.claude/skills/ - 用户级：
~/.claude/skills/
推荐做法：在你的项目根目录下创建符号链接。
cd /path/to/your/project
mkdir -p .claude/skills
ln -s ~/shared-agent-skills/code-review .claude/skills/code-review
ln -s ~/shared-agent-skills/generate-commit .claude/skills/generate-commit
ln -s ~/shared-agent-skills/debug-api .claude/skills/debug-api
或者，你也可以一次性链接整个技能库目录（仅当目录结构兼容时）：
ln -s ~/shared-agent-skills .claude/skills
第三步：为 Codex 创建符号链接
Codex 会扫描以下目录来发现 Skill：
- 项目级：
<项目根目录>/.agents/skills/ - 用户级：
$HOME/.agents/skills/
推荐做法：同样在你的项目根目录下创建符号链接。
cd /path/to/your/project
mkdir -p .agents/skills
ln -s ~/shared-agent-skills/code-review .agents/skills/code-review
ln -s ~/shared-agent-skills/generate-commit .agents/skills/generate-commit
ln -s ~/shared-agent-skills/debug-api .agents/skills/debug-api
第四步：验证链接是否生效
验证 Claude Code：
cd /path/to/your/project
claude
在 Claude Code 会话中输入 /skills，查看列表中是否包含你链接的技能。
验证 Codex：
cd /path/to/your/project
codex
在 Codex 会话中输入 /skills，查看列表中是否包含你链接的技能。
第五步：配置 Codex 启用多代理模式（可选）
为了让 Codex 能够更好地调用这些技能，建议在项目配置中启用多代理功能。
创建或编辑 .codex/config.toml：
[features]
multi_agent = true
注意事项
| 注意事项 | 说明 |
|---|---|
| 配置格式差异 | Claude Code 使用 settings.json，Codex 使用 config.toml。这只影响 Skill 的开关设置，不影响 SKILL.md 的内容本身。 |
| 专有字段兼容性 | 如果 SKILL.md 中使用了 Claude Code 的专有字段（如 context: fork、allowed-tools 等），Codex 会忽略它们，但不影响基本功能的执行。 |
| 相对路径问题 | 如果 Skill 内部引用了相对路径的资源文件，请确保这些资源也在符号链接的范围内，或使用绝对路径。 |
| 同步更新 | 修改 ~/shared-agent-skills/ 中的任一 SKILL.md 文件后，所有通过符号链接访问它的 Agent 都会自动获得更新，无需额外操作。 |
常见问题
Q：为什么 Claude Code 的 /skills 列表中看不到链接的技能？
A：Claude Code 有时不会在列表中显示通过符号链接添加的技能，但通过名称直接调用（如 /code-review）通常是有效的。如果不放心，可以用命令测试一下。
Q：如果我要添加一个新 Skill，需要重新链接吗？
A：需要。将新的 SKILL.md 放入 ~/shared-agent-skills/ 后，需要为 Claude Code 和 Codex 分别创建新的符号链接。
Q：能否让 Claude Code 和 Codex 共享同一份用户级配置？
A：不可以直接共享，因为两个工具的配置格式不同（JSON vs TOML）。但你可以通过脚本自动同步两个配置文件中的共同部分。
总结
| 步骤 | 核心操作 |
|---|---|
| 1. 统一存放 | 所有 SKILL.md 放在 ~/shared-agent-skills/ |
| 2. 链接到 Claude | 在 .claude/skills/ 下创建符号链接 |
| 3. 链接到 Codex | 在 .agents/skills/ 下创建符号链接 |
| 4. 验证 | 分别在两个工具中执行 /skills 确认 |
完成以上步骤后，Claude Code 和 Codex 就可以共享和调用同一套 Skill 了。