MemoryLake
返回全部文章
Tutorial2026 年 11 月 18 日·11 分钟阅读

如何在不丢失上下文的情况下将 Codex Skills 迁移到 Claude Code (2026)

在过去的几个月里,你在 Codex 中构建了一套 skills:一个用于准备发布,一个用于按照团队喜好编写迁移脚本,还有一个用于分流不稳定的测试。现在,你的一部分工作在 Claude Code 中运行,你希望在那里使用相同的 skills。你将一个文件夹复制到仓库中,打开 Claude Code,输入 skill 的名称,却什么也没出现。

Skill 本身没有问题,只是放错了地方。Codex 和 Claude Code 都使用相同的 skill 格式,但各自在特定的文件夹中查找 skills。OpenAI 的文档指出:“对于仓库,Codex 会扫描从当前工作目录到仓库根目录的每个目录中的 .agents/skills。”而 Claude Code 则在 .claude/skills/ 中查找。

本指南涵盖了 skill 在每种工具中的定义、各自的查找位置、哪些内容可以原封不动地迁移、哪些内容无法一一对应、两种迁移方案、如何保留单份副本而非两份,以及无论使用哪种工具,如何保持 skills 背后的推理过程始终可用。

Codex 和 Claude Code 中的 skill 是什么

这两种工具都基于相同的开放标准。OpenAI 的文档称:“Skills 构建在开放 agent skills 标准之上。”Anthropic 则表示:“Claude Code skills 遵循 Agent Skills 开放标准,该标准可跨多个 AI 工具工作。”

在 Codex 中,OpenAI 描述了其结构:“一个 skill 是一个包含 SKILL.md 文件以及可选脚本和引用的目录。SKILL.md 文件必须包含 name 和 description。”一个 skill 文件夹还可以包含 scripts/、references/、assets/ 以及一个 agents/openai.yaml 文件。

在 Claude Code 中,skill 同样是一个包含 SKILL.md 文件的文件夹。--- 标记之间的 frontmatter 告诉 Claude 何时使用该 skill,下方的 markdown 则包含指令。

因此,skill 的核心——文件夹、SKILL.md 文件、其 name、description 和指令——在两种工具中格式是相同的。这对于迁移来说是个好消息。大部分工作在于位置调整以及处理每种工具在标准之上添加的少量特定部分。

每种工具在哪里查找 skills

这解释了开头的例子。

Codex 从仓库、用户、管理员和系统位置读取 skills:

  • 仓库: 当前工作目录及直到仓库根目录的每个文件夹中的 .agents/skills。
  • 用户: $HOME/.agents/skills,适用于任何仓库的 skills。
  • 管理员: /etc/codex/skills,机器上共享的 skills。
  • 系统: 随 Codex 捆绑的 skills,例如 skill-creator 和 skill-installer。

Claude Code 从以下位置读取 skills:

  • 项目: 仓库中的 .claude/skills/<skill-name>/SKILL.md。
  • 个人: ~/.claude/skills/<skill-name>/SKILL.md,适用于该机器上的所有项目。
  • 企业: 由组织部署的托管设置目录。
  • 插件: 已启用的插件中捆绑的 skills。

这两种工具的文档都没有列出对方的文件夹。因此,请预料到 .agents/skills 中的 skill 在放入 .claude/skills/ 之前不会出现在 Claude Code 中,反之亦然。

对于 monorepos(单体仓库),还有一个区别。Anthropic 的文档称 Claude Code “从启动目录及其直到仓库根目录的每个父目录中的 .claude/skills/ 加载项目 skills”。它补充道:“启动目录之下的 .claude/skills/ 目录中的 skills 不会在启动时加载。”它们会在 Claude 第一次读取或编辑该子目录中的文件时加载。

哪些内容可以原封不动地迁移

由于两种工具都遵循相同的标准,你编写最多的部分可以照搬:

  • 文件夹名称和 SKILL.md。 结构是相同的。
  • name 和 description。 两种工具都使用描述来决定何时应用某个 skill。
  • 指令。 Markdown 正文是纯文本,任何一种工具都可以遵循。
  • 支持文件。 skill 文件夹内的脚本、引用和模板会随之迁移。

迁移后,描述部分值得再次检查。OpenAI 对 Codex 的建议是“编写范围和边界清晰的简练描述”。Anthropic 的文档为 Claude Code 增加了一个限制:“在 skill 列表中,description 和 when_to_use 的组合文本会被截断至 1,536 个字符,以减少上下文占用。”在 Codex 中很长但没问题的描述,在 Claude Code 的列表中可能会被截断。

哪些内容无法一一对应

Codex skill 的某些部分是特定于 OpenAI 产品的。

agents/openai.yaml。 OpenAI 描述了此文件的用途:“添加 agents/openai.yaml 以在 ChatGPT 桌面应用中配置 UI 元数据、设置调用策略,并声明工具依赖项,从而获得更无缝的 skill 使用体验。”它包含显示名称和图标、隐式调用策略以及 MCP server 等依赖项。Claude Code 的 skill 文档并未描述读取此文件的行为。

调用策略。 在 Codex 中,该文件的 policy 部分包含 allow_implicit_invocation 等设置。Claude Code 在 frontmatter 中有自己的字段来实现相同的想法:disable-model-invocation。文档称:“设置为 true 以防止 Claude 自动加载此 skill。”如果你在 Codex 中关闭了某个 skill 的隐式调用,请在迁移后的 SKILL.md 中设置此字段。

工具依赖。 如果 Codex skill 在 openai.yaml 中声明了一个 MCP server,Claude Code 需要单独配置该服务器。检查 skill 的指令在没有它的情况下是否仍然有效,或者将该服务器添加到 Claude Code 中。

如何调用 skill。 在 Codex CLI 或 IDE 扩展中,OpenAI 建议“运行 /skills 或输入 $ 来提及某个 skill”。在 Claude Code 中,你直接使用 /skill-name 调用 skill。

重名问题。 OpenAI 指出:“如果两个 skills 共享相同的 name,Codex 不会合并它们;两者都会出现在 skill 选择器中。”Claude Code 也会保留同名的嵌套 skills。如果你正在合并 skill 集,请在依赖它们之前重命名任何冲突的项。

方案 1:使用 /import

Claude Code 有一个专门的命令。其命令参考将 /import 描述为一种将机器上来自 OpenAI Codex 和其他编码 agent 的配置引入 Claude Code 的方式,“包括指令文件、MCP servers、命令、子 agent 和 skills”。

有两个选项可以让运行更安全:

  • 先预览。 参考说明:“添加 --dry-run 进行预览而不写入任何内容,或添加 --yes 跳过交互式选择器。”
  • 从终端运行。 claude import 会启动一个运行 /import 的交互式会话,具有相同的选项。

当你设置新项目时,如果 /init 发现了任何 Codex 配置,它也会提议通过 /import 进行迁移。

在运行之前,Anthropic 的记忆文档中有一个细节值得阅读。它提到 /import “会将 AGENTS.md 等指令文件的一次性副本追加到匹配的 CLAUDE.md 中,并迁移 MCP servers、命令、子 agent 和 skills”。

关键词是一次性副本。导入后,你的 AGENTS.md 和 CLAUDE.md 是独立的文件。如果你下个月更改了 AGENTS.md 中的约定,除非你也更新 CLAUDE.md 或再次运行导入,否则 Claude Code 将看不到该更改。同样的逻辑也适用于 skills:一旦 skill 被复制,编辑 Codex 版本不会改变 Claude Code 版本。

文档并未描述 /import 如何处理 agents/openai.yaml 或其他 OpenAI 特有的元数据。导入后,请在 Claude Code 中打开每个 skill 并检查其 frontmatter 和支持文件。

方案 2:通过符号链接(Symlink)保留单份副本

如果你打算同时使用这两种工具,每个 skill 的两个副本将会产生偏差。这两种工具都支持符号链接的 skill 文件夹,这让你能够保留单一来源。

OpenAI 的文档称:“Codex 支持符号链接的 skill 文件夹,并在扫描这些位置时遵循符号链接目标。”

Anthropic 则表示,企业、个人或项目位置中的 skill 条目可以是指向磁盘其他位置目录的符号链接。“Claude Code 从目标读取 SKILL.md,即使有多个位置指向同一个目标,也只会加载一次该 skill。”

一个简单的布局是将每个 skill 保存在一个真实的文件夹中,并让另一个工具的位置指向它:

  • 将 skill 保存在 .agents/skills/release-notes/,Codex 可以在这里找到它。
  • 添加 .claude/skills/release-notes 作为指向该文件夹的符号链接。

这样,对同一个 SKILL.md 的编辑就能同时触达两种工具。Codex 会“自动检测 skill 更改”,其文档建议如果更新未出现则重启 Codex。如果编辑内容未在 Claude Code 中显示,请启动新会话。

有两个注意事项。符号链接的 skill 共享一个描述,因此编写描述时要兼顾两种工具的列表显示。此外,Claude Code 特有的 frontmatter(如 disable-model-invocation)将存在于 Codex 也会读取的文件中,因此在添加后请测试 Codex 是否仍能正常加载该 skill。

个人 skills

同样的原则也适用于你为自己保留而非放在仓库中的 skills。Codex 从 $HOME/.agents/skills 读取个人 skills。Claude Code 从 ~/.claude/skills/ 读取。你可以复制它们、运行 /import 或为单个 skill 文件夹创建符号链接。

Anthropic 的文档在个人位置保留了一个文件夹名称。Claude Code 使用 ~/.claude/skills/synced/ 存放从你的 claude.ai 账户下载的 skills,因此不要将你自己的 skill 命名为 synced。

如果你之前曾进行过反向迁移,插件也遇到过相同的位置和打包问题。我们在将 Claude Code 插件迁移到 Codex 的指南中涵盖了那个方向。

开始前需要检查的内容

  • 你实际使用的 skills。 迁移是丢弃无人调用的 skills 的好时机。
  • 哪些 skills 依赖于 OpenAI 特有的元数据。 查找带有调用策略或 MCP 依赖项的 agents/openai.yaml 文件。
  • 你是否会继续使用 Codex。 如果是,请计划使用符号链接。如果不是,复制或 /import 就足够了。
  • 名称冲突。 比较两种工具中的 skill 名称。
  • 你的 AGENTS.md。 决定 Claude Code 应该读取副本,还是你会同时维护这两个文件。

人们最常尝试的操作

将 .agents/skills 复制到仓库并期望 Claude Code 找到它。 Claude Code 读取的是 .claude/skills/。

假设 /import 会保持文件同步。 它只是追加了指令文件的一次性副本。

指望 openai.yaml 设置能自动迁移。 如果某个 skill 不应自动运行,请在 Claude Code 中设置 disable-model-invocation。

保持长描述不变。 Claude Code 会在列表中截断组合描述文本。

维护同一个 skill 的两个副本。 它们会产生偏差。如果同时使用两种工具,请使用符号链接。

手动迁移步骤

第 1 步:列出你的 Codex skills

收集仓库中 .agents/skills、$HOME/.agents/skills 以及你使用的任何管理员位置中的 skills。

第 2 步:预览导入

在 Claude Code 中运行带有 --dry-run 的 /import,查看它会迁移哪些内容。

第 3 步:导入或链接

运行导入,或者从 .claude/skills/ 创建指向你打算保留在原处的 skill 文件夹的符号链接。

第 4 步:调整 frontmatter

在关闭了隐式调用的 Codex skill 中添加 disable-model-invocation,并缩短过长的描述。

第 5 步:重新连接依赖项

配置 skill 通过 openai.yaml 依赖的任何 MCP servers。

第 6 步:按名称测试每个 skill

使用 /skill-name 调用每个 skill,然后尝试一个应该自动触发它的请求。

更好的方法:将 skills 背后的原因集中管理

Skill 记录了如何执行任务。而背后的原因——例如为什么发布检查清单有一个手动步骤,哪种迁移模式取代了旧模式,或者测试分流 skill 绝不能触碰什么——都是项目上下文。当你跨工具移动 skills 时,指令会随之迁移,但它们为何如此编写的历史可能只存在于某人的记忆中。

MemoryLake 是此类项目上下文(如决策、约定和工作流背后的原因)的记忆层,它集中在你维护的一个地方,并可供你连接的助手(如 ChatGPT、Claude Code 和 Codex)使用。

你用自己的语言亲自编写条目。不会从你的 skill 文件夹、SKILL.md 文件、AGENTS.md 或 CLAUDE.md 文件、Codex 或 Claude Code 设置或任何厂商的存储中读取、写入或删除任何内容。Skills 和 /import 仍按 OpenAI 和 Anthropic 描述的方式工作。

第 1 步:创建 API 密钥

登录并在控制面板生成密钥。像对待其他凭据一样,将其存储在仓库之外。

MemoryLake 控制台显示 API 密钥屏幕,在此处创建并复制新密钥以供 agent 使用
MemoryLake 控制台显示 API 密钥屏幕,在此处创建并复制新密钥以供 agent 使用

第 2 步:上传你的第一批记忆

从你在手动迁移第 1 步中列出的 skills 开始。对于每一个 skill,写下它存在的原因以及它绝不能更改的内容。每个条目对应一个 skill。

MemoryLake 工作区显示已上传的首批文档,列出每个文件成为可搜索记忆的过程
MemoryLake 工作区显示已上传的首批文档,列出每个文件成为可搜索记忆的过程

第 3 步:连接你的 AI 和 agents

连接 Claude Code、Codex 以及你使用的其他助手。无论哪种工具运行该 skill,它们都可以借鉴相同的原因。

MemoryLake 集成屏幕列出了可以连接到记忆层的 AI 客户端和 agent 框架
MemoryLake 集成屏幕列出了可以连接到记忆层的 AI 客户端和 agent 框架

这在实践中改变了什么

第一个区别是迁移更简洁。Skills 可以精简为纯指令,因为历史背景存在于别处。

第二个是跨工具的一致性。在 Claude Code 和 Codex 中都可以获得相同的推理依据。

第三个是更新更简单。当约定发生变化时,你只需更新一个条目以及遵循该约定的 skill。

将 Codex Skills 迁移到 Claude Code 的最佳实践

将 skills 放在 Claude Code 查找的位置。 使用 .claude/skills/ 或 ~/.claude/skills/。

导入前先预览。 使用 --dry-run。

记住这是一次性复制。 指令文件在 /import 后不会保持同步。

如果同时使用两种工具,请使用符号链接。 单个文件夹可避免偏差。

转换调用策略。 在 Claude Code 中使用 disable-model-invocation。

保持描述简短。 两种工具都根据描述进行匹配,且 Claude Code 会截断长描述。

按名称和按请求进行测试。 检查手动和自动调用。

结论

Codex 和 Claude Code 使用相同的 skill 格式,均基于开放 agent skills 标准,因此 skill 的文件夹、SKILL.md、名称、描述和指令可以原封不动地迁移。不同之处在于每种工具的查找位置:Codex 为 .agents/skills,Claude Code 为 .claude/skills/。agents/openai.yaml 中的 Codex 特有元数据需要 Claude Code 的等效项,例如 disable-model-invocation。

你可以通过 /import 迁移 skills(它还会追加 AGENTS.md 等指令文件的一次性副本),或者通过两种工具都遵循的符号链接保留单份副本。无论采用哪种方式,迁移后请检查每个 skill,并将 skills 背后的原因保存在两种工具都能使用的地方。

常见问题

Claude Code 可以使用 Codex skills 吗?

可以。两者都遵循相同的开放标准。将 skill 文件夹移动或链接到 .claude/skills/,以便 Claude Code 能够找到它。

Claude Code 在哪里查找 skills?

在项目及其父目录的 .claude/skills/ 中、在 ~/.claude/skills/ 中、在托管设置中以及已启用的插件中。

/import 会迁移 Codex skills 吗?

会。Claude Code 的命令参考将 skills 列在 /import 引入的配置中,此外还包括指令文件、MCP servers、命令和子 agent。

/import 会保持 AGENTS.md 和 CLAUDE.md 同步吗?

不会。Anthropic 的文档称它只是追加了指令文件的一次性副本。

我可以为两种工具使用同一个 skill 文件夹吗?

可以。Codex 和 Claude Code 都支持符号链接的 skill 文件夹。

agents/openai.yaml 会怎样?

Claude Code 的 skill 文档并未描述读取它的行为。请在 SKILL.md 中设置等效选项,例如 disable-model-invocation。

如何在 Claude Code 中调用迁移后的 skill?

输入 / 后跟 skill 名称,或者描述一个与其描述相匹配的任务。