Preface¶

In 2026, few developers rely on only one AI coding tool. You might use Cursor for frontend work, Claude Code for long-running tasks, and Codex for CI integrations. When switching between them, the most time-consuming part is rarely learning new interfaces—it’s reconfiguring rules, Skills, MCP servers, and sub-Agents from scratch. The same set of “project memories” is scattered across paths like .claude/, .cursor/, AGENTS.md, and .mcp.json, each with its own format. Manually editing configs by cross-referencing documentation can easily eat up half a day.

OpenAI maintains a curated Skill called migrate-to-codex in the official openai/skills repository. It includes a Python migration script and a difference comparison table that can convert instruction files, Skills, sub-Agents, Hooks, and MCP configurations supported by Claude Code into project-level or global Codex artifacts (such as AGENTS.md, .agents/skills/, .codex/config.toml, and .codex/agents/). If you are migrating from Cursor, Codex CLI 0.145’s /import command can batch import Cursor settings first. For edge cases that /import cannot automatically handle, you can use this Skill for fine-grained supplementary migration.

What is this¶

migrate-to-codex is an Agent Skill from OpenAI that follows the standard SKILL.md format, and can be enabled in Codex CLI, Cursor, Claude Code, and other tools that support Skills.

One-sentence positioning: Structurally migrate Claude Code’s configuration surface to match Codex’s official directory specifications, and output a reviewable migration report.

The core problem it solves is this: While both Claude Code and Codex are based on the Agent Skills open standard, their configuration filenames, Hook runtimes, MCP fields, and sub-Agent permission models are not fully equivalent. Manually editing TOML files by cross-referencing two documentation sets is prone to missing items and difficult to track which configurations have been migrated and which require manual review. The migrate-to-codex Skill streamlines this process by scanning the source directory, previewing changes, performing official migrations, and validating the target output.

Core Features and Highlights¶

1. Covers the full range of Claude Code configurations¶

The official references/differences.md lists the migration mapping relationships, covering the following source → target conversions:

Plugin trees (.claude/plugins/) and marketplace configurations will not be copied automatically, and will be marked as manual_fix_required in the report, requiring manual handling.

2. Built-in CLI migration tool with “review before write” support¶

The scripts/migrate-to-codex.py script in the Skill directory provides a complete command-line interface. A typical workflow is:
- --scan-only: Only scan the source directory and list active and disabled configuration surfaces
- --plan: Print the paths of the Codex artifacts that will be generated without writing files
- --doctor: Summarize readiness, risk items, and content requiring manual review
- --dry-run: Simulate the migration without making actual changes
- --validate-target: Validate the migrated Codex directory for TOML parsing, Skill frontmatter, MCP command availability, and other checks

After the migration is complete, the report will be written to .codex/migrate-to-codex-report.txt. The Agent will also output a Markdown table in accordance with specifications, marking each item with one of three statuses: Added, Check before using, and Not Added.

3. Self-Healing Migration Loop¶

After enabling this Skill, the Agent will follow official guidelines to complete the entire migration process continuously without stopping to ask for confirmation at each step:
1. List specific steps using Codex’s built-in TODO tool
2. Read references/differences.md (marked “Docs last checked: 2026-04-20”; update per the latest Codex documentation if outdated)
3. Run --plan / --doctor first, then --dry-run, and perform the official migration after confirmation
4. Fix blocks marked ## MANUAL MIGRATION REQUIRED in generated files
5. Run --validate-target and output the final report once validation passes

Important constraints: It will not modify the original Claude Code files (.claude/, ~/.claude/, .mcp.json, .claude.json), nor will it touch unrelated project code or secrets. Entries in existing Codex configurations that are unrelated to the migration (such as notify, projects, and other MCP servers) will be preserved.

4. Complementary to Codex /import¶

Codex CLI 0.145 (released July 21, 2026) expanded the /import command to batch import settings, MCPs, plugins, sessions, commands, and more from Cursor and Claude Code. The migrate-to-codex Skill, by contrast, excels at fine-grained Claude Code → Codex conversions and semantic rewriting when 1:1 mapping is not possible (for example, downgrading allowed-tools to prompt guidance, or restricting PreToolUse Hooks to only shell commands in Codex).

Recommended practice: Use /import first for bulk rough migration, then use migrate-to-codex to handle the Check before using and Not Added items in the report.

Installation and Enablement¶

Install in Codex¶

The official documentation recommends using the built-in installer to pull the curated Skill:

$skill-installer migrate-to-codex

You can also manually clone it to a user-level or repository-level Skill directory (Codex automatically discovers Skills from paths like $HOME/.agents/skills/ and the in-repo .agents/skills/):

git clone --depth 1 https://github.com/openai/skills.git /tmp/openai-skills
cp -r /tmp/openai-skills/skills/.curated/migrate-to-codex ~/.agents/skills/migrate-to-codex

After installation, the migration script is usually located at:

.codex/skills/migrate-to-codex/scripts/migrate-to-codex.py

(The exact path depends on where the Skill is installed; the Skill uses the environment variable MIGRATE_TO_CODEX to point to this script.)

If you modified the Skill toggle in ~/.codex/config.toml, you will need to restart Codex for changes to take effect.

Enable in Cursor¶

Cursor supports the universal Skill format. Copy the migrate-to-codex directory (including SKILL.md, scripts/, and references/) to the project’s .cursor/skills/migrate-to-codex/, or call it explicitly with @migrate-to-codex in a chat. Codex migration scripts will not run automatically in Cursor—this setup is better suited for generating migration plans and manually editing configurations by cross-referencing differences.md.

Enable in Claude Code¶

Similarly, place the migrate-to-codex directory under ~/.claude/skills/migrate-to-codex/ or the project’s .claude/skills/ directory. Calling this Skill in Claude Code is primarily intended for previewing what the Codex configuration will look like after migration; the original Claude Code environment will not be modified.

Typical Usage Examples¶

Scenario A: Migrate global Claude Code configuration to Codex user directory¶

First scan, plan, and perform a dry run:

MIGRATE_TO_CODEX='python3 .codex/skills/migrate-to-codex/scripts/migrate-to-codex.py'

$MIGRATE_TO_CODEX --source ~/.claude/ --scan-only
$MIGRATE_TO_CODEX --source ~/.claude/ --target ~/.codex/ --plan
$MIGRATE_TO_CODEX --source ~/.claude/ --target ~/.codex/ --doctor
$MIGRATE_TO_CODEX --source ~/.claude/ --target ~/.codex/ --dry-run

After confirming everything is correct, remove --dry-run to perform the official migration and validate the result:

$MIGRATE_TO_CODEX --source ~/.claude/ --target ~/.codex/
$MIGRATE_TO_CODEX --validate-target ~/.codex/

Scenario B: Migrate a single repository’s project-level configuration¶

$MIGRATE_TO_CODEX --source ./.claude/ --target ./.codex/ --dry-run
$MIGRATE_TO_CODEX --source ./.claude/ --target ./.codex/
$MIGRATE_TO_CODEX --validate-target ./.codex/

If you want to clean up orphaned Skills or Agents generated during the migration, add the --replace flag (this will delete generated artifacts in the target directory that no longer have a corresponding source item; please back up your data before using this option).

Scenario C: Trigger migration with natural language in Codex¶

After installing the Skill, enter a prompt like the following in the Codex CLI or IDE extension:

Please use migrate-to-codex to migrate the configuration from ~/.claude/ to ~/.codex/.
First run --doctor to check for risks, then do a dry-run, and I will confirm before proceeding with the official migration. Finally, validate the result and share the migration report table.

The Skill’s description states “Migrate supported instruction files, skills, agents, and MCP config into Codex project and global files”, and Codex will load it implicitly when the task matches. You can also call it explicitly with $migrate-to-codex.

What the migration report looks like¶

The final output is required to be a Markdown table, for example:

When you see Check before using, open the corresponding generated file and search for ## MANUAL MIGRATION REQUIRED to follow the prompts for modifications.

Applicable Scenarios and Notes¶

Who this is for¶

• Teams or individuals who have accumulated a large number of Skills, slash commands, sub-Agents, and MCP configurations in Claude Code and plan to switch to Codex
• Users who ran Codex /import and still have a large number of “requires manual review” items in the report, and want scripts and Agents to help implement each item one by one
• Users who need to maintain both tools in parallel for a period of time and want to first standardize the Codex directory structure

Known Limitations (Please Read Carefully)¶

1. Reference document scope: references/differences.md is explicitly labeled “Claude Code to Codex migration only”. Cursor Rules (.cursor/rules) are not included in this Skill’s automatic scan range; Cursor users should prioritize using Codex /import or manually merge rules into AGENTS.md.
2. No semantic equivalence guarantee: Fields such as allowed-tools, permissionMode, and some Hook types will be rewritten as prompt guidance or partially mapped; Claude Hooks like Notification and PermissionRequest have no direct equivalent in Codex.
3. MCP transport differences: Claude’s type: sse is not supported by Codex; Bearer authentication will be converted to bearer_token_env_var, but default values in the format ${VAR:-default} will not be preserved.
4. Plugins require manual setup: Claude plugin directories and marketplace configurations are only reported, not copied; you will need to adapt them to Codex’s plugin specifications (such as .agents/plugins/marketplace.json) manually.
5. Back up before using --replace: We recommend backing up ~/.codex/config.toml and the project’s .codex/ directory before performing an official migration; --replace may delete orphaned Skills/Agents in the target directory.
6. Credentials will not be automatically re-authenticated: MCP server names and connection parameters will be migrated, but OAuth tokens and other credentials will still need to be re-logged in or configured as environment variables in the new environment.

Conclusion¶

Switching between multiple tools has become the norm for developers in 2026. The value of migrate-to-dex lies in turning the most tedious configuration comparison work from “Claude Code → Codex” into a scanable, previewable, verifiable, and reportable pipeline. Combined with Codex /import for bulk imports from Cursor, the “moving cost” of switching tools will be greatly reduced.

Official Skill address: github.com/openai/skills/tree/main/skills/.curated/migrate-to-codex

Codex Skills documentation: developers.openai.com/codex/skills