skills.rest
Aki2022
Aki2022COMMUNITY
Explore all skills by this author →
GitHub

migrate-to-codex

Migrate Claude Code instructions, skills, agents, hooks, and MCP config into Codex project files.

Updated Dec 9, 2025
Search Tags:#claude code#codex#migration#subagents#configuration#mcp#ai coding assistant
One-click install
npx skills add https://github.com/Aki2022/skills --skill migrate-to-codex-aki2022
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: migrate-to-codex
Source: https://github.com/Aki2022/skills/tree/main/migrate-to-codex
Command: npx skills add https://github.com/Aki2022/skills --skill migrate-to-codex-aki2022

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve? Moving an existing Claude Code setup to Codex requires manually rewriting instruction files, slash commands, subagents, hooks, and MCP server configuration into Codex formats like AGENTS.md, .agents/skills, .codex/agents TOML, and .codex/config.toml, which is error-prone and tedious. ## Core Features & Use Cases - Automated surface conversion: Converts CLAUDE.md instructions, .claude/commands, .claude/skills, .claude/agents, settings hooks, and .mcp.json MCP servers into their Codex equivalents with partial-mapping caveats preserved as manual-review notes. - Plan, doctor, and validate workflow: Supports --scan-only, --plan, --doctor, --dry-run, and --validate-target modes so you can inspect readiness, staged artifacts, and post-migration validity before and after writing files. - Use Case: You have a project with .claude/commands, three subagents, and an .mcp.json file. Run the migrator against ./.claude/ targeting ./.codex/, review the generated report table, fix flagged manual items, and validate the resulting Codex configuration. ## Quick Start Migrate my Claude Code configuration from ./.claude/ into Codex files under ./.codex/ and show me the migration report.

Frequently Asked Questions about migrate-to-codex

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I migrate Claude Code settings to Codex?▼

Run the migrate-to-codex script with --source pointing at your .claude directory and --target at your .codex directory. It converts instructions, skills, commands, subagents, hooks, and MCP servers, then writes a migration report listing anything needing manual review.

How to convert Claude slash commands into Codex skills?▼

The migrator converts each .claude/commands/*.md file into a one-file Codex skill under .agents/skills/. Argument placeholders, allowed-tools, and shell interpolation are preserved as manual-review prompt text since Codex handles them differently.

Can I preview the migration before writing any files?▼

Yes. Use --scan-only to inventory sources, --plan to see staged artifact paths, --doctor for readiness and risk counts, and --dry-run to render the full report without writing. Nothing is created until you run without --dry-run.

Does the migration support Claude hooks and MCP servers?▼

Partially. Supported hook events like PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, and Stop are rewritten into .codex/hooks.json with codex_hooks enabled. MCP servers from .mcp.json or .claude.json are converted into config.toml mcp_servers tables, with unsupported fields flagged.

What Claude Code features are not migrated automatically?▼

Plugin trees and marketplaces are reported as manual work only. Unsupported items include SSE MCP servers, prompt/agent/async hooks, skill-level model pins, settings.local.json, and subagent fields like memory, background, and maxTurns.

How do I verify the migrated Codex setup is valid?▼

Run the script with --validate-target against the target directory. It checks config.toml parses, skill frontmatter is valid, agent TOML files have required fields, AGENTS.md size, and MCP command availability, exiting nonzero on errors.

Related Skills

Explore More Software Engineering Skills→
johnendjohnend
23

audit-claude-setup

Compare Claude Code configuration against official documentation and generate a remediation plan.

Community
Advanced
VKirillVKirill
15

codex

Configure and run OpenAI Codex CLI with sandbox and approval policies.

Community
Advanced
jmagarjmagar

check-agent-parity

Compare Claude Code, Codex CLI, and Gemini CLI configurations for parity gaps.

Community
Advanced
racecraft-labracecraft-lab
3

install

Copy Codex subagent TOML templates into the user's Codex agents directory.

Official
Intermediate