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

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

在过去的一年里,你在 Claude 中构建了一些 skills。其中一个按照团队喜欢的格式排版发布说明;一个将会议记录转化为行动项;还有一个根据内部规则列表检查拉取请求。有些存在于 Claude 的设置中,以 ZIP 文件形式上传;另一些位于 ~/.claude/skills,因为你是为 Claude Code 编写的。现在你更多地使用 Codex,并希望在那里拥有相同的 skills。

好消息是,这两个工具都基于相同的格式。OpenAI 的 Codex 文档指出:“Skills 构建在开放代理技能标准之上。”Anthropic 的文档也以同样的方式描述 Claude skills,即以 SKILL.md 文件为核心的指令、脚本和资源文件夹。

工作的难点在于细节:每种 Claude skill 存放的位置、Codex 导入器会提取哪些、Codex 读取哪些 frontmatter 字段,以及哪些 Claude Code 特性无法迁移。本指南涵盖了所有这些内容,以及在文件移动时如何保留每个 skill 背后的逻辑。

各方对 skill 的定义

Anthropic 的帮助中心用一句话定义了 skill:“Skills 是指令、脚本和资源的文件夹,Claude 会动态加载它们,以提高在专门任务上的性能。”

OpenAI 的定义非常接近:“一个 skill 是一个包含 SKILL.md 文件以及可选脚本和引用的目录。SKILL.md 文件必须包含 name 和 description。”

这两个工具加载 skills 的方式大致相同。Codex 从每个 skill 的名称和描述开始,并在决定使用某个 skill 时加载完整的指令。Anthropic 也将 Claude 的版本描述为渐进式披露,即 Claude 审查可用的 skills 并加载相关的 skills。

因此,一个 skill 文件夹基本上是可移植的。问题在于如何将每一个 skill 放入 Codex 读取的位置,以及在迁移过程中需要更改什么。

你的 Claude skills 存放在哪里

你的 skills 可能存放在三个地方,每个地方的迁移方式都不同。

Claude 应用中的 Skills。 这些是你在聊天中创建或作为 ZIP 文件上传到 claude.ai 或 Claude Desktop 的 skills。它们存在于你的账户中,而不是电脑上的文件夹里。Anthropic 的帮助中心解释了如何获取副本:在 skills 列表中找到该 skill,打开其详情,然后下载。在更新后的布局中,skills 列表位于 Plugins 下,它取代了 Customize 菜单。

Claude Code 中的 Skills。 个人 skills 存放在 ~/.claude/skills/<skill-name>/SKILL.md。项目 skills 存放在代码库的 .claude/skills/ 中。插件 skills 存放在插件内部。

从 claude.ai 同步到 Claude Code 的 Skills。 当你使用 claude.ai 账户登录 Claude Code 时,Claude Code 会将你账户的 skills 下载到 ~/.claude/skills/synced/。这些是应用 skills 的副本,而不是独立的源文件。文档说明在那里的编辑不会同步回去,因此请将应用版本视为源头。

在移动任何内容之前,请列出每个位置的 skills 并标记哪些是重复的。

Codex 导入器会迁移什么

Codex 有一个导入流程,它涵盖了部分内容。根据 OpenAI 的导入文档,ChatGPT 桌面应用可以从 Claude Code、Claude Cowork 或 Cursor 导入,而 CLI 可以从 Claude Code 或 Cursor 导入。在 CLI 中,你在空闲会话中运行 /import。

其导入项目列表包括 skills(会进入 Codex skills)和斜杠命令(也会变成 skills)。文档还提供了一项在迁移期间很重要的保证:“导入不会更改或删除你现有的代理设置。”

因此,对于存放在 Claude Code 中的 skills,导入器是首选尝试方案。对于你在 Claude 应用中制作的 skills,导入文档并未将 Claude 应用列为来源。如果你使用 Cowork,请检查桌面应用导入列表提供的选项。对于未列出的任何内容,请下载 skill 并手动安装。

我们在将 Claude Code 插件迁移到 Codex的指南中介绍了导入器如何处理 Claude Code 插件(插件可以将 skills 与 hooks 和 MCP 服务器捆绑在一起)。

Codex 在哪里读取 skills

Codex 从四种位置读取 skills:

  • 代码库 (Repository): 当前文件夹及其上方直到代码库根目录的每个文件夹中的 .agents/skills。
  • 用户 (User): $HOME/.agents/skills,用于你希望在每个代码库中都可用的 skills。
  • 管理员 (Admin): /etc/codex/skills,共享的系统位置。
  • 系统 (System): 随 Codex 捆绑的 skills,包括 skill-creator 和 skill-installer。

路径与 Claude Code 不同。~/.claude/skills/ 中的个人 Claude Code skill 对应 Codex 中的 ~/.agents/skills/。代码库中 .claude/skills/ 的项目 skill 对应代码库中的 .agents/skills/。

Codex 处理重复名称的方式也不同。文档指出:“如果两个 skills 共享相同的 name,Codex 不会合并它们;两者都会出现在 skill 选择器中。”如果你导入了一个 skill,然后又手动复制了同一个,你最终会得到两个。

哪些 frontmatter 字段可以保留

这是需要进行编辑的地方。

Anthropic 的文档将 skill frontmatter 分为两组。Claude Code 接受一长串字段。但对于 claude.ai skill 上传和 Skills API,仅允许六个字段:name、description、license、compatibility、metadata 和 allowed-tools。

这产生了一个有用的结果。你上传到 Claude 应用的 Skills 已经使用了共享格式,因此它们需要的编辑最少。

为 Claude Code 编写的 Skills 可能会使用仅 Claude Code 响应的字段,例如 argument-hint、disable-model-invocation、paths、context、model、effort 或 hooks。Codex 的文档要求 name 和 description,并未描述其他字段,因此不要指望它们在 Codex 中起作用。

其中一些有 Codex 对应的替代方案:

  • disable-model-invocation: true 防止 Claude 自行调用 skill。在 Codex 中,通过在可选的 agents/openai.yaml 文件中将 allow_implicit_invocation 设置为 false 可以达到同样的效果。OpenAI 的文档称,Codex 之后将不会隐式调用该 skill,显式调用仍然有效。
  • 缺失的 name 在 Claude Code 中可行,它会回退到文件夹名称。Codex 要求必须有名称,所以请添加一个。

在编辑时顺便检查一下描述。当安装了许多 skills 时,Codex 会缩短描述,其文档建议:“将关键用例和触发词放在前面,这样即使描述被缩短,主机仍然可以匹配该 skill。”

正文中哪些内容无法迁移

Claude Code 支持 skill 指令内部的一些其他工具不支持的特性。Anthropic 的文档指出了它们:“仅限 Claude Code 的正文特性,如动态上下文注入,在 claude.ai 聊天或通过 API 均无法运行。”

迁移到 Codex 时同样适用。请查找:

  • 注入输出的 Shell 行,在命令前带有感叹号。Claude Code 在加载 skill 之前运行它们。
  • 占位符,例如 ${CLAUDE_PROJECT_DIR} 和参数替换。
  • 文件引用,带有 Claude Code 附加的 @ 符号。

OpenAI 的导入文档在导入后需要检查的项目中列出了相同的类别:“依赖于参数、shell 插值或文件路径占位符的提示词模板或命令式提示词。”将这些重写为普通指令,或者将命令移动到 skill 的 scripts/ 文件夹中的脚本中,并告诉 Codex 何时运行它。

在 Codex 中开启和关闭 skills

一旦你的 skills 就位,你可能希望其中一些可用但保持静默。Codex 允许你禁用 skill 而不删除它,方法是在 ~/.codex/config.toml 中使用 [[skills.config]] 条目。每个条目通过路径指向一个 skill 或匹配具有给定名称的所有 skill,并将其设置为禁用。OpenAI 的文档补充说,当多个条目匹配一个 skill 时,最后一个匹配的条目获胜。

如果你添加的 skill 没有显示,文档称 Codex 会自动检测 skill 更改,并补充道:“如果更新未出现,请重启 Codex。”更改配置文件后同样适用。

Skills 内部的工具权限

Claude Code 的 allowed-tools 字段会为调用 skill 的轮次预先批准工具。OpenAI 的导入文档将“导入的 skills 和代理中的工具限制或权限”列为导入后需要检查的内容。

Codex 有自己的权限模型,包含沙箱、批准和命令规则。在 Claude Code 中无需提示即可运行的 skill 在 Codex 中可能会请求批准。在添加更广泛的规则使其静默之前,请决定这是否是你想要的行为。

工作区 skills 与共享

如果你也在 ChatGPT 中使用 skills,OpenAI 的 skill 控制文档区分了三种类型:ChatGPT 工作区 skills、本地文件系统 skills 和插件。它警告说:“移动 skill 不会转移 ChatGPT 工作区所有权、共享、角色分配、插件安装状态或连接器授权。”

因此,你的团队在 Claude 中共享的 skill 在到达 Codex 时不会处于共享状态。为了给团队提供相同的 skill,OpenAI 的文档建议将其打包为插件,这在 Codex 和 ChatGPT 中都适用。

人们首先尝试的操作

将 skills 复制到 ~/.codex。 Codex 从 ~/.agents/skills 读取用户 skills。

期望导入器能找到 Claude 应用的 skills。 请下载这些并手动安装。

保留仅限 Claude Code 的字段。 Codex 要求 name 和 description,不识别其他字段。

保留 shell 注入行。 它们是 Claude Code 的特性。

导入并复制同一个 skill。 Codex 会保留两者。

手动迁移步骤

第 1 步:列出你的 Claude skills

检查 Claude 应用的 skills 列表、~/.claude/skills 以及每个代码库的 .claude/skills。

第 2 步:为 Claude Code skills 运行导入器

在 Codex CLI 中使用 /import,或在 ChatGPT 桌面应用设置中使用 Import。

第 3 步:下载你的 Claude 应用 skills

从详情页面保存每个自定义 skill 并解压缩。

第 4 步:将每个 skill 放置在 Codex 读取的位置

个人 skills 使用 ~/.agents/skills,代码库 skills 使用 .agents/skills。

第 5 步:编辑 frontmatter

保留 name 和 description,并将调用设置移动到 agents/openai.yaml。

第 6 步:重写仅限 Claude Code 的正文特性

用指令或脚本替换 shell 注入和占位符。

第 7 步:测试每个 skill

使用 $ 或 /skills 调用它,然后检查匹配的请求是否触发了它。

更好的方法:将 skills 背后的逻辑集中管理

一个 skill 记录了如何执行任务。而其背后的原因——例如为什么发布说明遵循该结构、哪个评审者要求了某条规则,或者某一步骤处理了哪个边缘情况——可能不在文件中。当文件移动到新工具时,步骤到达了,但推理逻辑仍留在某个人的记忆中。

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

你用自己的语言编写条目。不会从你的 Claude skills、Codex skills 文件夹、config.toml、插件或任何供应商商店中读取、写入或删除任何内容。Skills 仍按 Anthropic 和 OpenAI 描述的方式工作。

第 1 步:创建 API 密钥

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

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

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

从手动迁移第 1 步中列出的 skills 开始。对于每一个,写下它的用途以及其规则存在的原因。每个条目对应一个 skill。

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

第 3 步:连接你的 AI 和代理

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

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

这在实践中改变了什么

第一个区别是更容易编辑。当你了解规则存在的原因时,你就能判断 Codex 的重写是否保留了其原意。

第二个区别是更简洁的 skills。快速变化的事实不再放在 SKILL.md 中,而是放在你单独更新的笔记中。

第三个区别是跨工具的一致性。在你同时使用 Claude Code 和 Codex 时,两者都可以获得相同的原因。

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

从导入器开始。 它处理 Claude Code skills 并保持你的 Claude 设置不变。

将应用 skills 视为源头。 Claude Code 中的同步副本不会保存回去。

使用共享字段。 name 和 description 在两个工具中都有效。

将描述关键信息前置。 Codex 可能会缩短它们。

避免重复名称。 Codex 不会合并它们。

将共享 skills 打包为插件。 共享关系不会随文件移动。

结论

Claude 和 Codex 基于相同的开放格式构建 skills,因此包含 SKILL.md 文件的 skill 文件夹大多是可移植的。Codex 的导入器可以在不更改 Claude 设置的情况下迁移 Claude Code skills 和斜杠命令,而你在 Claude 应用中制作的 skills 则需要手动下载并放置在 ~/.agents/skills 或代码库的 .agents/skills 中。

上传到 Claude 应用的 skills 已经使用了共享字段。为 Claude Code 编写的 skills 可能需要修剪其 frontmatter,将调用设置移动到 agents/openai.yaml,并重写仅限 Claude Code 的特性(如 shell 注入)。共享关系、所有权和连接器授权不会随文件移动,因此请单独规划这些内容。

常见问题

Codex 可以使用 Claude skills 吗?

可以。两者都基于开放代理技能标准,因此 SKILL.md 文件夹经过一些编辑后可以迁移。

Codex 会从 Claude 导入 skills 吗?

Codex 的导入器可以迁移 Claude Code skills。来自 Claude 应用的 skills 需要手动下载并添加。

我应该把 Codex 的 skills 放在哪里?

个人 skills 使用 ~/.agents/skills,代码库中的 skills 使用 .agents/skills。

如何从 Claude 下载 skill?

在 skills 列表中打开该 skill 的详情并下载。

Codex 需要哪些 frontmatter?

必须包含 name 和 description。

如何阻止 Codex 自动使用某个 skill?

在 skill 的 agents/openai.yaml 中将 allow_implicit_invocation 设置为 false。

导入会改变我的 Claude Code 设置吗?

不会。OpenAI 表示导入不会更改或删除你现有的设置。