| name | migrate-to-codex |
| description | Migrate Claude-era skills into native Codex skill artifacts with a preservation-first workflow. Also migrate project-local Claude slash commands and command hooks in batch mode as review-required Codex artifacts. Classify migration risk, preserve control shape, validate runtime-coupling leaks, and require a Codex nativeness audit before calling the result native. Use for "migrate skill to codex", "convert skill to codex", "port skills", or "codex compatibility". This skill does not migrate agents. |
Migrate to Codex
Preserve the source workflow first. The goal is not to transliterate Claude
primitives. The goal is to produce the Codex skill artifact that best preserves
the source skill's behavior.
Conversation-First Entry
Bare or vague requests should not dump raw script flags immediately. Resolve the
request through the shared contract in
references/conversational-migration-contract.md.
Default menu for underspecified requests:
- Assess one skill
- Preview one skill
- Migrate one skill live
- Batch assess pending skills
- Review one migrated skill for nativeness
- Explain blockers and statuses
Routing rules:
- If the user already says
assess <skill>, preview <skill>, or
migrate <skill>, or review <skill>, route directly.
- In Plan mode, use
request_user_input for the action choice only.
- Outside Plan mode, render the same choices as a numbered text menu.
- If the action needs a skill name and the user did not provide one, ask for it
in plain text.
- Require explicit confirmation before any live write into
.codex/skills/.
Advanced CLI
- Preferred wrappers:
python3 .codex/skills/migrate-to-codex/scripts/migration_doctor.py --skill example-skill --json
python3 .codex/skills/migrate-to-codex/scripts/run_migration_workflow.py --preview --skill example-url-validator --json
python3 .codex/skills/migrate-to-codex/scripts/run_migration_workflow.py --skill example-url-validator --json
- Power-user engine:
python3 .codex/skills/migrate-to-codex/scripts/migrate_claude_workflows_to_codex.py --analysis-only --json --skill example-skill
python3 .codex/skills/migrate-to-codex/scripts/migrate_claude_workflows_to_codex.py --skill example-url-validator
python3 .codex/skills/migrate-to-codex/scripts/migrate_claude_workflows_to_codex.py --all
python3 .codex/skills/migrate-to-codex/scripts/migrate_claude_workflows_to_codex.py --all --dry-run --json
python3 .codex/skills/migrate-to-codex/scripts/migrate_claude_workflows_to_codex.py --analysis-only --json
Explicit Non-Goals
- Do not attempt to preserve inline Claude
Agent() / Task() semantics mechanically in this skill.
- Do not migrate agents here. Route agent dependencies to
migrate-agents-to-codex at .codex/skills/migrate-agents-to-codex/SKILL.md.
- Do not treat legacy
.codex/agents/*.md imports as resolved runtime dependencies. Only .codex/agents/*.toml counts.
- Do not treat command-derived skills or generated hook config as native/trusted
output. They are compatibility artifacts that require manual review.
Sandbox Policy
Recommended mode: workspace-write
Rationale: this workflow creates skill files, updates repo-local documentation,
and runs validation scripts. Infrastructure or deployment access is not needed.
Runtime Contract
- Codex callable MCP namespaces use underscore-normalized server names.
- Hard MUST / NEVER / ONLY constraints survive verbatim.
- Preserve the source workflow's control shape unless Codex lacks a required primitive.
- Preserve direct execution when Codex supports it. Only redesign into manager-to-subagent when the source truly depends on task/team semantics.
- Do not invent
spawn_agent, wait_agent, update_plan, or approval requirements unless the source workflow genuinely needs them.
- User interaction is mode-dependent:
request_user_input exists only in Plan mode; outside Plan mode rely on normal user messages or approval workflow.
- File edits use
apply_patch when the workflow actually edits files.
- Explicitly named Claude agents that exist under
.claude/agents/*.md are hard runtime dependencies. Never substitute, downgrade, drop, or neutralize them during skill migration. If .codex/agents/<name>.toml is missing, stop and route to migrate-agents-to-codex.
- Claude skill references are context-sensitive. Only operational uses are hard migration dependencies. Related-skills tables, troubleshooting notes, provenance/history, and redirected-skill markers are not blockers by themselves.
- For ambiguous skill mentions, the Python migrator extracts structured candidates and returns
MANUAL_REVIEW_REQUIRED. The interactive Codex skill then owns the read-only mini-auditor pass. If the auditor still cannot classify a mention confidently, keep the skill in manual-review state rather than auto-blocking or auto-migrating.
Reference Map
| Reference | Load when |
|---|
references/primitive-mapping.md | You need authoritative primitive translation rules or sandbox inference |
references/embedded-agent-taxonomy.md | The source skill embeds Claude Agent(...) or Task(...) sub-agent sites and you must distinguish inline slices from named agent dependencies |
references/complexity-classifier.md | You need to decide Tier 1 vs Tier 2 vs Tier 3 |
references/codex-skill-template.md | You are hand-authoring a Tier 3 native skill |
references/architectural-patterns.md | You need preservation-first rules or runtime-coupling checks |
references/conversational-migration-contract.md | You need the shared menu/direct-routing/confirmation rules for the migrate-* family |
../migrate-agents-to-codex/SKILL.md | You need the agent-only migration workflow or its direct script entrypoint |
docs/how-to/claude-to-codex-agentic-migration.md | You need the repo-level migration contract and CLI examples |
Scripts
| Script | Purpose |
|---|
.codex/skills/migrate-to-codex/scripts/migrate_claude_workflows_to_codex.py | Deterministic migration engine with preflight classification, --analysis-only, and additive --json structured output |
.codex/skills/migrate-to-codex/scripts/migration_doctor.py | Read-only readiness layer for the migration family: blocker counts, existing validator failures, drift, pending nativeness review, and oversized packages |
.codex/skills/migrate-to-codex/scripts/run_migration_workflow.py | Script-driven orchestration: doctor -> migrate -> validate -> tracker refresh -> dashboard summary, with optional materialized preview and markdown evidence report |
tools/migration_support/ | Shared migration-family support package for tracker CLI, tracker state, nativeness handoff, and repo-root path helpers |
tools/migration_support/validate_names.py | Thin wrapper around the shared Codex migration validator |
Discovery Summary
- Agent targets are out of scope and must be routed to
migrate-agents-to-codex.
- Project-local Claude command markdown files are converted only in batch/all
mode into single-file skills named
command-* under .codex/skills/.
- Project-local Claude settings command hooks are converted only in batch/all
mode into the Codex hooks config file.
Generated hooks are always reported as "Check before using."
- Embedded agent sites are a dependency-classification problem first: separate inline delegated slices from file-backed named agent dependencies before any primitive rewrite.
- The migrator now classifies first:
MECHANICAL_SAFE, MANUAL_REVIEW_REQUIRED, REFACTOR_REQUIRED, or BLOCKED.
- Root CLI compatibility matters: zero-argument execution must remain valid even if the implementation moves under
.codex/skills/.
- Provenance markers are not automatically runtime coupling; treat active docs, active scripts, and live references as the real completion gate.
- Tier 3 migrations usually fail when they are treated as textual conversion instead of behavior-preserving rewrite.
Known Corrections
- Banner insertion must happen after YAML frontmatter, never before it.
- Primitive mapping is semantic, not textual. A source primitive name appearing in documentation does not mean the workflow should be auto-rewritten around the nearest Codex tool.
- Legacy Claude skill-call syntax is context-sensitive during source analysis. Cross-references in prose, tables, and examples are dependency metadata, not orchestration. Operational workflow steps that invoke sibling skills still require rewrite.
- Embedded
Agent(...) syntax alone is not enough to choose a migration strategy. What matters is whether the spawned thing is an inline behavior slice or a referenced runtime artifact under .claude/agents/.
- Inline Claude orchestration forms are refusal triggers here, not transformation targets.
- Plan-mode-only user-input primitives are not universal replacement targets. Outside Plan mode, normal user interaction or approval flow is the correct fallback.
- Runtime-coupling checks must distinguish active dependencies from provenance-only strings.
- Only
.codex/agents/<name>.toml satisfies a named agent dependency. .md files are legacy imports and ignored.
- If a named Claude agent exists in
.claude/agents/, it is a hard dependency edge. Missing Codex parity is a stop condition, not a substitution opportunity.
- If a referenced skill exists only in the Claude tree, it is a hard dependency edge only when the mention is operational. Support or provenance mentions are evidence to classify, not blockers by themselves.
Migration State
- Default status is
CODEX_COMPATIBLE_BUT_NOT_NATIVE until Step 5 passes.
- Any mechanically generated artifact enters
pending_native_review after
write. File existence may unblock downstream migrations, but native status
still requires a recorded manual nativeness review.
- Command-generated
command-* skills enter the same pending_native_review
state. Hook config is operational-review-required and is not native-tracked in
v1.
- No migration may be marked
NATIVE if any active consumer-side script or active doc still points to the old source asset path for that workflow.
- Preserve the source tree. Do not delete or rewrite the source skill unless the user explicitly asks for cutover work.
- Agent migration is OUT OF SCOPE. If the target is a Claude agent, stop and route to
migrate-agents-to-codex.
BLOCKED means a hard dependency is unresolved: either a named agent runtime dependency or an operational referenced skill that still exists only in the legacy Claude skill tree. Migrate that dependency first.
MANUAL_REVIEW_REQUIRED means the deterministic classifier found unresolved ambiguous references to Claude-only skills. Do not mechanically migrate until the Codex-layer adjudicator or a human resolves them.
REFACTOR_REQUIRED means unsafe orchestration exists and the skill must be hand-authored or manually refactored.
MECHANICAL_SAFE means no inline orchestration forms, hard dependency blockers, or unresolved ambiguous Claude-only references remain, so deterministic migration may proceed.
User Checkpoints
| Checkpoint | When to stop |
|---|
| Dependency resolution | An operational referenced skill exists only in the legacy Claude skill tree, an ambiguous mention still needs manual classification, or a named agent still lacks a .codex/agents/*.toml contract |
| Audit escalation | Step 5 still returns any CRITICAL or HIGH findings after the convergence pass |
| Judgment-required rewrite | A fix changes behavior rather than restoring compatibility |
Workflow
0. Resolve Interaction Mode
Before running any backend script, decide whether the user gave a directly
actionable request or needs the family menu:
- direct intent + skill name -> route immediately
- direct intent + missing skill name -> ask for the missing target
- vague request -> show the menu from
references/conversational-migration-contract.md
- explicit
review <skill> on an already migrated skill -> skip migration
write logic and jump to Step 5 as a read-only nativeness audit
Preferred execution path:
assess -> python3 .codex/skills/migrate-to-codex/scripts/migration_doctor.py --json ...
preview -> python3 .codex/skills/migrate-to-codex/scripts/run_migration_workflow.py --preview --json ...
migrate live -> same workflow without --preview, but only after an
explicit confirmation step
Keep raw migrate_claude_workflows_to_codex.py usage as the power-user path,
not the default conversational front door.
Named --skill <name> execution is intentionally narrow: it processes only the
named Claude skill package and does not convert command files or hook settings
as a side effect. Batch mode (--all or zero-argument execution) processes
non-archived skills plus project-level command and hook surfaces.
1. Resolve Gold Standard and Assess Targets
Context: The user provides one skill, a batch of skills, or --all.
Why first: bad target classification causes the rest of the workflow to produce polished but invalid output.
Action:
- Confirm
examples/hello-world-skill/SKILL.md exists. If it does not, fail fast or fall back explicitly to the template and pattern references.
- Reject agent targets immediately. This workflow accepts Claude skills only; if the request points at
.claude/agents/ or names an agent spec, route to migrate-agents-to-codex.
- Scan the skill body and active references for embedded agent sites using
references/embedded-agent-taxonomy.md:
- inline ephemeral
Agent( / Task( blocks with in-body prompt, model, and mode
- named file-backed agents where
subagent_type, role, or routing-table outputs match .claude/agents/*.md
- mixed routing tables: every reachable named agent is a dependency edge until proven otherwise
- Run preflight classification before any transform:
BLOCKED if a named agent dependency exists but .codex/agents/<name>.toml is missing, or if an operational Claude-only skill dependency is confirmed
REFACTOR_REQUIRED if inline Agent() / Task() forms, routing tables, or orchestration primitives survive
MANUAL_REVIEW_REQUIRED if unresolved ambiguous references to Claude-only skills remain
MECHANICAL_SAFE only when those risks are absent
- Classify each skill target with
references/complexity-classifier.md after preflight.
- Run the preservation gate before rewriting:
- Does Codex already support the source workflow directly?
- Does the source intentionally orchestrate direct tool calls?
- Does the source explicitly reject delegation?
- Are filesystem artifacts part of the execution contract?
- Do prompt templates rely on direct MCP or file access?
- Resolve cross-references before migrating. First classify each mention as operational, reference-only, or ambiguous.
- For named file-backed agents,
MIGRATE is the only valid action. Do NOT SUBSTITUTE, DROP, or NEUTRALIZE a named Claude agent dependency.
- For referenced skills, if the mention is operational and the source skill exists only in the legacy Claude skill tree with no Codex counterpart,
MIGRATE is the only valid action. Stop completely, tell the user you cannot proceed with migration because there is a hard dependency on that skill, and tell them to migrate that skill first.
- For ambiguous referenced skills, the Python CLI must emit structured candidate data via
--json and return MANUAL_REVIEW_REQUIRED. The interactive Codex skill then routes those candidates through a read-only gpt-5.4-mini auditor with reasoning_effort: "high". If the auditor returns operational_dependency, upgrade to BLOCKED. If it returns reference_only, clear the candidate. If it returns uncertain, remain in MANUAL_REVIEW_REQUIRED.
- For inline agent slices, preserve prompt/model/effort intent inline; do not convert them into external dependencies.
- Reference-only mentions in Related Skills, troubleshooting, provenance, redirects, or other non-operational prose may be neutralized or rewritten as prose. Do not neutralize a real Claude-only skill dependency once it is classified as operational.
- Skip skills whose entrypoint marks them archived or redirected immediately.
- Reframe invalid requests early:
- agent target -> route to
migrate-agents-to-codex
- repo-wide provenance cleanup -> treat as follow-up work, not proof that the current skill migration failed
- behavior-changing rewrite request -> stop and confirm that the user wants more than compatibility migration
Result: Each skill target is classified as MECHANICAL_SAFE, MANUAL_REVIEW_REQUIRED, REFACTOR_REQUIRED, or BLOCKED before any transform runs.
Anti-patterns:
- Do not auto-rewrite
TaskCreate -> spawn_agent before checking orchestration intent.
- Do not flatten inline prompt-defined agents and file-backed named agents into the same generic
spawn_agent rewrite.
- Do not discard inline model/effort intent by hardcoding generic defaults when the source says
opus, sonnet, or haiku.
- Do not process batch targets in arbitrary order when dependencies are unresolved.
- Do not use this skill to migrate agents. Use
migrate-agents-to-codex for .claude/agents/*.
- Do not substitute an explicitly named Claude agent with a generic worker, different agent, or prose fallback just to keep the skill migration moving.
- Do not rewrite around a referenced Claude-only skill dependency just because it appears in related-skills prose rather than an operational step.
2. Fix Tooling Once Per Session
Context: The migration scripts are shared infrastructure. Fix them once, then reuse them.
Why this phase exists: migration defects in shared tooling create repeated downstream drift, so fix the engine before fixing artifacts.
Action:
- Ensure banner insertion happens after YAML frontmatter.
- Expand primitive mappings using
references/primitive-mapping.md.
- Teach shared tooling to refuse unsafe automation and over-broad dependency blocking:
- inline agent slices trigger
REFACTOR_REQUIRED
- named agents trigger
.codex/agents/<name>.toml dependency checks
- operational referenced Claude skills trigger
.codex/skills/<name>/ dependency checks
- support tables, troubleshooting notes, related-skills sections, and provenance markers do not force
BLOCKED
- ambiguous referenced skills are emitted as structured candidates and return
MANUAL_REVIEW_REQUIRED instead of being auto-blocked or auto-migrated
- any missing named agent forces
BLOCKED, even if inline orchestration also exists
- legacy
.codex/agents/<name>.md files do not satisfy runtime dependencies
- Add or verify
--skill, --all, --dry-run, and --analysis-only.
- Preserve the root CLI contract: zero-argument execution must remain valid through the repo-level wrapper.
Result: The migration engine is safe to use for deterministic conversion.
Anti-patterns:
- Do not change the documented root CLI without an explicit compatibility contract.
- Do not treat mapping-table text as executable replacement targets.
3. Verify Domain Content Before Writing
Context: Skill content drifts. Verify first, write once.
Why this phase exists: stale paths and broken examples are expensive because they survive syntax validation and only fail when a later agent executes them.
Action:
- Check prompt template paths, file references, and code examples against the live repo.
- Replace unverifiable details with neutral prose rather than shipping stale guidance.
- Search the active docs, scripts, and migrated tree for old-source runtime coupling.
- For Tier 3, scan the full skill package, not just
SKILL.md.
Result: The output will not encode stale paths, broken references, or incorrect repo assertions.
Anti-patterns:
- Do not trust the source skill body as current without verification.
- Do not copy prompt templates containing stale file paths into the target artifact.
4. Execute the Migration
Why this phase exists: execution strategy must match tier; using the wrong path here is the main source of false “completed” migrations.
Tier 1:
- Run
python3 .codex/skills/migrate-to-codex/scripts/migrate_claude_workflows_to_codex.py --skill <name>.
- Copy non-markdown files with the migrated package.
- Treat the written artifact as
pending_native_review.
- Spot-check the output before relying on it operationally, then complete Step
5 before calling it native.
Tier 2:
- Run the mechanical conversion.
- Review MCP servers, sandbox choice, primitive semantics, and reference portability.
- Keep asset parity: migrate supporting references and scripts together.
Tier 3:
- Do NOT run mechanical conversion -- output would be non-functional.
- Read the gold standard and
references/codex-skill-template.md.
- Hand-author the native skill, preserving control shape and hard constraints.
- For embedded agents, branch by taxonomy:
- inline slice -> preserve as inline Codex
spawn_agent(...) pattern only when delegation is semantically required, and carry model/effort intent forward
- named dependency -> keep the dependency explicit, require
.codex/agents/<name>.toml, and surface it in references or consumption contracts
- Copy pure documentation reference files only when they are still correct after Step 3.
Result: A migrated skill package exists in .codex/skills/.
Classifier gate:
MECHANICAL_SAFE -> deterministic transform may proceed, but manual
nativeness review is still mandatory before native completion
MANUAL_REVIEW_REQUIRED -> refuse deterministic migration until the Codex-layer adjudicator or a human resolves the ambiguous references
REFACTOR_REQUIRED -> refuse and print action-oriented findings
BLOCKED -> refuse and print exact routing guidance for the unresolved dependency: migrate-agents-to-codex for agents, or "please migrate that skill first" for Claude-only skill dependencies
Anti-patterns:
- Mechanical conversion on Tier 3.
- Inventing new orchestration phases because Codex happens to have sub-agents.
5. Validate and Audit for Nativeness
Why this phase exists: structural validity is necessary but not sufficient; nativeness is a higher bar than “file parses”.
Review-only entry: If a skill already exists under .codex/skills/ and the
tracker says it is pending_native_review, this phase may be invoked directly
as a read-only single-skill review flow. In that entry path, audit first,
present findings plus next actions, and auto-record native by default when
the final audit result is NO_FINDINGS unless the user explicitly asked for
audit-only behavior.
Dashboard routing note:
migration-dashboard may use this review-only entry as a bounded Verify
phase after review next, review <number>, or review <name>.
- In that entry path, the parent dashboard remains a thin router. This skill
owns the reviewer prompt, delegated lifecycle, evidence-record guidance, and
tracker close-out instructions.
Structural validation:
- Run
python3 tools/migration_support/validate_names.py --scan-dir .codex/skills/<name>.
- Check YAML frontmatter, line count, naming, stale source-path leaks, absolute home paths, and missing local assets.
- When using preview mode, validate the preview package before touching the live
.codex/skills/ tree.
Native Codex compliance audit:
- MANDATORY: Step 5 MUST use inline
spawn_agent(...) -- NEVER external Codex review proxy or external large-context reviewer.
- The audit must verify that the execution contract was re-expressed in Codex terms without flattening the original control shape.
- Spawn one inline nativeness-audit sub-agent with
model: "gpt-5.4" and reasoning_effort: "high".
- Keep the auditor read-only by prompt contract: do not edit files, do not call
apply_patch, do not rerun migration scripts, and use shell only for verification commands such as grep, ls, sed, and cat.
- Use a persistent legacy-agent lifecycle for this audit loop:
spawn_agent(...) once for the first-pass audit
wait_agent({"targets": [agent["id"]]}) for findings
- parent applies CRITICAL and HIGH fixes locally
send_input(...) to the same live auditor for convergence
wait_agent({"targets": [agent["id"]]}) again
close_agent({ target: agent.id }) before leaving Step 5
- This lifecycle guidance is workflow-local. It does not weaken the global rule that
spawn_agent should be introduced only when the source workflow genuinely needs delegation.
- Keep the parent-thread return compact. For dashboard-driven entry, return only
verdict, top findings, next action, and evidence path. Do not paste
the full audit into the main thread.
- Fix CRITICAL and HIGH findings immediately with surgical edits.
- Run one convergence pass. Hard cap: two cycles.
- Save the full nativeness review to a markdown evidence record when the review is
meant to be recorded later. Reuse the existing migration evidence directories
or an explicit
/tmp review path, then attach that path through
--review-evidence at tracker close-out.
- After the final post-fix content is stable, record the nativeness result with:
python3 tools/migration_support/tracker.py --write --record-review skill:<name>=native
python3 tools/migration_support/tracker.py --write --record-review skill:<name>=codex_compatible_but_not_native
- For
NO_FINDINGS, use the native path by default with summary No findings after convergence.
- Keep manual close-out only when MEDIUM findings remain, when the user requested audit-only behavior, or when the tracker write fails.
- Do not leave the tracker at
pending_native_review after a clean nativeness audit.
Completion gate:
- The execution contract must be re-expressed in Codex terms without flattening the original control shape. If the result is mechanically compatible but semantically flattened, keep status at
CODEX_COMPATIBLE_BUT_NOT_NATIVE.
NO_FINDINGS: auto-record native and continue.
- MEDIUM only: continue with noted risks.
- Any CRITICAL or HIGH after convergence: stop and escalate.
Anti-patterns:
- Skip compliance audit because YAML passed.
- Let the auditor edit files.
- Respawn a fresh auditor for convergence when
send_input(...) to the existing auditor would preserve the same review frame.
- Loop audit for more than two cycles.
- Soften MUST/NEVER/ONLY during compression.
6. Report
Why this phase exists: the caller needs a migration status, not just modified files.
Report each migration with:
- Tier
- Target path
- Status:
NATIVE, CODEX_COMPATIBLE_BUT_NOT_NATIVE, or SKELETON_ONLY
- Sandbox recommendation
- Validation status
- Codex compliance result
- Assets copied
- References rewritten or intentionally preserved
- Remaining risks
- Evidence report path if the workflow used
.codex/skills/migrate-to-codex/scripts/run_migration_workflow.py
- Preview root if
--preview materialized output outside the live target tree
For batch mode:
- Assess all targets first.
- Process Tier 1 in batch.
- Queue Tier 2 for sequential review.
- Queue Tier 3 for hand-authoring.
- For nativeness review of a completed migrated batch, auditors may run in
bounded parallel waves when write scopes do not overlap, for example
3 parallel auditors -> parent fixes -> convergence -> 3 parallel auditors.
- End with a consolidated summary and recorded review outcomes.
Anti-patterns:
- Report completion before Step 5 is finished.
- Declare native while active docs or scripts still depend on the old source asset path.
- Report agent migration status from this skill. Agent targets belong to
migrate-agents-to-codex.
Verification Checklist