ccode-to-codex

Experimental toolkit for migrating Claude Code skills and agents into the Codex ecosystem. It converts reusable workflows into Agent Skill packages, reusable roles into custom-agent TOML files, normalizes MCP tool namespaces for Codex, and preserves delegation behavior through native Codex subagent orchestration where appropriate.

⚠ Experimental — interfaces, artifact layouts, and validation rules may change without notice.

What it is

This repository is a migration system:

Claude source artifacts -> migration workflows -> Codex-native outputs

Claude source artifacts live under .claude/skills/ and .claude/agents/. The migration workflows live in this repository as Codex skill packages and Python scripts. The generated outputs land under .codex/skills/ and .codex/agents/, with validation and tracker state to keep the migration auditable.

Key architectural decision: migration is not blind transliteration

The goal is to preserve workflow intent first, then express that behavior using native Codex surfaces. In practice, this means SKILL.md packages for workflows, .codex/agents/*.toml custom agents for reusable roles, underscore-normalized MCP tool namespaces, and spawn_agent(...)-style orchestration only for source workflows that genuinely delegate work.

Current capabilities

• Migrate Claude skills into Codex Agent Skill packages.
• Migrate Claude agents into Codex custom-agent TOML outputs.
• Classify blockers, dependency gaps, and manual-review cases before writes.
• Normalize MCP namespaces from source tool references into Codex-callable form.
• Preview or dry-run migrations before touching live .codex/ outputs.
• Validate migrated artifacts, refresh migration-state.json, and inspect progress with the dashboard.
• Provide minimal reference examples for both Agent Skills and custom agents.

What is actually required today

• Python 3.11+
• PyYAML>=6.0.2,<7 (installed via requirements.txt)
• Claude source inputs under .claude/skills/ and/or .claude/agents/
• OpenAI Codex CLI when consuming or exercising migrated .codex/ outputs

To invoke these migration workflows as Codex skills in a target repository, install the operational packages under that repository’s .codex/skills/ directory. The .claude/skills/ and .claude/agents/ directories are source inputs only; the migration reads them and writes Codex-facing outputs under .codex/.

mkdir -p /path/to/target-repo/.codex/skills
cp -R .codex/skills/migrate-to-codex /path/to/target-repo/.codex/skills/
cp -R .codex/skills/migrate-agents-to-codex /path/to/target-repo/.codex/skills/
cp -R .codex/skills/verify-skill-migration /path/to/target-repo/.codex/skills/
cp -R .codex/skills/migration-dashboard /path/to/target-repo/.codex/skills/

Direct Python scripts can still be run from this checkout without installing the Codex skills first. Mechanically generated artifacts are Codex-compatible first; they should pass nativeness review before being treated as native.

Repository layout

Included migration skills

• migrate-to-codex — transform Claude skills into Codex skill packages.
• migrate-agents-to-codex — transform Claude agents into Codex agents.
• verify-skill-migration — post-migration validation of a single skill.
• migration-dashboard — summary and status view across the tracker.

Useful commands

python3 -m pip install -r requirements.txt
python3 -m compileall -q tools/migration_support
python3 tools/migration_support/validate_names.py --scan-dir .codex/skills
python3 tools/migration_support/validate_names.py --scan-dir examples
python3 tools/migration_support/tracker.py --write
python3 .codex/skills/migration-dashboard/scripts/analyze_migration.py --status
python3 .codex/skills/migrate-to-codex/tests/test_migrate_claude_workflows_to_codex.py
python3 .codex/skills/migrate-agents-to-codex/tests/test_migrate_claude_agents_to_codex.py

How it fits with Codex CLI

The outputs under .codex/skills/ and .codex/agents/ are the Codex-facing artifacts this toolkit produces. After running the migration workflows against your Claude inputs, review and validate the generated tree before relying on it in Codex. See docs/how-to/claude-to-codex-agentic-migration.md for the end-to-end walkthrough.

Source

This repository is the public artifact of a private upstream toolchain. Only reviewed content is published here.

Contributing

See CONTRIBUTING.md.

License

MIT.