[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M70F6BZ832QAPF9BH7Q5WDT3":3,"skill-same:01M70F6BZ832QAPF9BH7Q5WDT3":118},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":44,"linkOnly":45,"markdownContent":46,"markdownBody":47,"frontMatter":48,"refName":49,"commitSha":50,"skillDirectory":51,"forksCount":52,"repositoryHtmlUrl":53,"repositoryHomepageUrl":6,"ownerHtmlUrl":54,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":55,"install":56,"resources":69},"01M70F6BZ832QAPF9BH7Q5WDT3","migrate-agents-to-codex",null,"Migrate Claude agent definitions (.claude\u002Fagents\u002F*.md) to Codex-compatible markdown or TOML outputs under `.codex\u002Fagents\u002F`. Strips frontmatter, maps fields to native Codex contracts, normalizes MCP namespaces, and classifies agents into 3 tiers. Includes adversarial cross-model review (GPT-5.4 inline native sub-agent) with auto-fix loop before completion. Use when asked to \"migrate agents to codex\", \"convert agents\", or \"port agent definitions\". Pipeline stage: CODE → VERIFY.","zuharz\u002Fccode-to-codex","zuharz","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F105288148?v=4","01M70F65DSYJQHWNJ06TKHG454","Sergejs","01M70F65EJFRJZTWRB3YJ43TKJ",75,"MIT","https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fmigrate-agents-to-codex\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43],"migrate agents to codex","codex","migrate","auto","when","auto-fix","sub-agent","inline","frontmatter","native","port","maps","MCP","fix","model","loop","markdown","pipeline","code","review","2026-11-10 10:12:30",false,"---\nname: migrate-agents-to-codex\ndescription: >-\n  Migrate Claude agent definitions (.claude\u002Fagents\u002F*.md) to Codex-compatible\n  markdown or TOML outputs under `.codex\u002Fagents\u002F`. Strips frontmatter,\n  maps fields to native Codex contracts, normalizes MCP namespaces, and\n  classifies agents into 3 tiers. Includes adversarial cross-model review\n  (GPT-5.4 inline native sub-agent) with auto-fix loop before completion. Use when asked to\n  \"migrate agents to codex\", \"convert agents\", or \"port agent definitions\".\n  Pipeline stage: CODE → VERIFY.\n---\n\n\u003C!-- Generated by the ccode-to-codex mirror sync on 2026-04-14 from input revision 9a2403fb. -->\n# Migrate Agents to Codex\n\n## Purpose\n\nMigrates Claude agent definitions from `.claude\u002Fagents\u002F*.md` (YAML frontmatter\n+ markdown body) to Codex-compatible outputs under `.codex\u002Fagents\u002F`.\n\nPreferred output: standalone TOML custom-agent files.\nBackward-compatible output only: pure-markdown behavioral specifications.\n\nThe migration strips frontmatter, maps fields to native Codex contracts,\npreserves runtime hints such as `model`, `effort`, `reasoning_effort`, and\n`model_reasoning_effort`, normalizes MCP namespaces, and extracts large domain\ncontent into companion reference files.\n\nAfter migration, a **native Codex compliance audit** (GPT-5.4 inline\nsub-agent) validates every migrated file passes as a native Codex sub-agent —\nnot a ported Claude artifact. Mechanical output is never final on write alone:\nevery mechanically generated agent requires a recorded manual nativeness review\nbefore it may be treated as native. Findings are auto-addressed and a\nconvergence check confirms no regressions were introduced by the fixes.\n\nPipeline position: **CODE → VERIFY** (runs during implementation phase).\nCovers 2 stages: CODE (migration) + VERIFY (adversarial review loop).\n\nCanonical conversation wrapper:\n`.codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Frun_agent_migration_workflow.py`\nDeterministic engine:\n`.codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Fmigrate_claude_agents_to_codex.py`\n\n## Conversation-First Entry\n\nBare requests should start with a user-facing action menu, not a wall of CLI\nflags. Follow the shared contract in\n`..\u002Fmigrate-to-codex\u002Freferences\u002Fconversational-migration-contract.md`.\n\nDefault menu for underspecified requests:\n\n1. Assess one agent\n2. Preview one agent as TOML\n3. Migrate one agent live\n4. Batch preflight all agents\n5. Review one migrated agent for nativeness\n6. Explain MCP or skill blockers\n\nRouting rules:\n\n- If the user already says `preview example-agent-e`, `migrate example-agent-c`,\n  or `review example-agent-e`, route directly.\n- In Plan mode, use `request_user_input` only for the action choice.\n- Outside Plan mode, render the same action set as a numbered text menu.\n- If the action still needs an agent name, ask for it in plain text.\n- Require explicit confirmation before any live write into `.codex\u002Fagents\u002F` or\n  any `--force` overwrite.\n\n## Advanced CLI\n\n- Preferred wrappers:\n  - `python3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Fmigrate_claude_agents_to_codex.py --agent example-agent-a --dry-run --json`\n  - `python3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Frun_agent_migration_workflow.py --preview --agent example-agent-a --json`\n  - `python3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Frun_agent_migration_workflow.py --agent example-agent-a --json`\n- Power-user engine:\n  - `python3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Fmigrate_claude_agents_to_codex.py --all --format toml`\n\n## Prerequisites\n\n- Python 3.11+ available\n- Sibling skill exists: `.codex\u002Fskills\u002Fmigrate-to-codex\u002F` (provides shared functions)\n- `.codex\u002Fagents\u002F` directory will be created by the script if missing\n- `.codex\u002Fconfig.toml` exists with MCP server definitions\n- Gold standard reference if present: a previously migrated agent artifact under\n  `.codex\u002Fagents\u002F`\n- Shared conversation contract available at\n  `..\u002Fmigrate-to-codex\u002Freferences\u002Fconversational-migration-contract.md`\n\n## Format: Markdown vs TOML\n\nOfficial Codex custom-agent format is TOML under `.codex\u002Fagents\u002F*.toml`.\n\nUse:\n\n- `--format toml` for new migrations\n- `--format md` only for backward-compatible markdown outputs\n\nRules:\n\n- If both `.md` and `.toml` exist for the same agent, treat `.toml` as the\n  runtime-preferred artifact.\n- Markdown remains useful as documentation and as a bridge for older migration\n  runs, but new custom agents should default to TOML.\n- Validation must branch by format. A TOML migration is not complete if the\n  workflow still validates only markdown headings.\n\n## Step 1: Assess Complexity & Resolve Dependencies\n\n**Context**: User provides an agent name, a list, `--all`, or a bare request\nthat still needs the menu\u002Ffront-door routing.\n\nBefore running the backend:\n\n- bare request -> show the family menu from the shared conversational contract\n- explicit action + explicit target -> route directly\n- explicit action + missing target -> ask for the target name\n- explicit `review \u003Cagent>` on an already migrated agent -> skip migration\n  write logic and jump to Step 5 as a read-only nativeness audit\n- live migration -> require confirmation before the write step\n\n### 1a. Classify\n\nClassify each target agent using the decision tree in\n[agent-complexity-classifier.md](references\u002Fagent-complexity-classifier.md).\n\nRun the assessment path through the backend wrapper or execute directly:\n\n```bash\npython3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Frun_agent_migration_workflow.py --preview --agent example-agent-a --json\npython3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Fmigrate_claude_agents_to_codex.py --all --dry-run --json\n```\n\nThe script parses each `.claude\u002Fagents\u002F*.md`, extracts frontmatter, counts\nMCP tools, detects hooks\u002Forchestration patterns, and outputs a classification\ntable with tier, readiness score, sandbox recommendation, dependency blockers,\nand next actions.\n\n**Skip rules:**\n- Agents with existing native `.codex\u002Fagents\u002F{name}.toml` or legacy\n  `.codex\u002Fagents\u002F{name}.md`\n  → SKIP (validate only)\n- Use `--force` to overwrite existing agents\n\n**Classification output:**\n\nUse generated classification output from the current input batch. Do not hard-code source-agent rosters in this skill.\n\n\n### 1b. MCP Dependency Preflight\n\nBefore resolving skill dependencies or writing any migrated agent, run an MCP\ndependency preflight against the project-level `.codex\u002Fconfig.toml`.\n\nRules:\n\n- Source of truth is the Claude agent frontmatter `tools:` list only.\n- Extract required MCP servers only from tools matching\n  `mcp__\u003Cserver>__\u003Ctool>`.\n- Treat `ide` as a Claude-only built-in integration, not a project MCP\n  dependency. Record it as unsupported source tooling and drop it from migrated\n  agent dependency requirements.\n- Normalize server ids to project config-key form before comparison\n  (`example_server_g` → `example-server-g`, `chrome_devtools` → `chrome-devtools`).\n- Read only top-level `[mcp_servers.\u003Cid>]` entries from `.codex\u002Fconfig.toml`.\n  Nested tables such as `[mcp_servers.\u003Cid>.tools.*]` do not count as separate\n  servers.\n- Agent-local output must not synthesize `[mcp_servers.*]` stanzas. Missing\n  server config is resolved only by editing project `.codex\u002Fconfig.toml`.\n\nBlocker behavior:\n\n- `--agent \u003Cname> --dry-run`: always print required\u002Fconfigured\u002Fmissing MCP\n  servers and preview the generated output.\n- `--agent \u003Cname>` in write mode: if `missing_mcp_servers` is non-empty, print\n  a blocker report, write nothing, and exit non-zero.\n- `--all --dry-run`: report MCP status for every agent, including all blocked\n  agents and their missing servers.\n- `--all` in write mode: preflight the full batch first. If any target agent is\n  blocked, write nothing for the whole batch and exit non-zero.\n\nSource-specific dependency notes:\n\n- Treat unsupported source tooling such as `ide` as input data, not as an MCP blocker.\n- Do not hard-code the current repository's agent roster or dependency state into public guidance.\n\n\n### 1c. Resolve Skill Dependencies\n\nFor each agent being migrated, cross-reference its `skills:` frontmatter\nagainst what exists in `.codex\u002Fskills\u002F`:\n\n```bash\n# Extract skills from Claude agent\ngrep '^  - ' .claude\u002Fagents\u002F{name}.md | sed 's\u002F^  - \u002F\u002F'\n\n# Check which exist in Codex\nls .codex\u002Fskills\u002F\n```\n\nProduce a dependency table:\n\n```\nAgent: \u003Cexample role> (Tier 3)\nSkills: 5 declared, 3 available, 2 MISSING\n  ✅ api-proxy-pattern-example              → .codex\u002Fskills\u002Fapi-proxy-pattern-example\u002FSKILL.md\n  ✅ frontend-interaction-example  → .codex\u002Fskills\u002Ffrontend-interaction-example\u002FSKILL.md\n  ✅ api-contracts-example          → .codex\u002Fskills\u002Fapi-contracts-example\u002FSKILL.md\n  ❌ example-url-validator             → NOT IN .codex\u002Fskills\u002F\n  ❌ example-feature-implementation → NOT IN .codex\u002Fskills\u002F\n```\n\n**If all skills are available** → READY. Proceed to Step 2.\n\n**If any skills are missing** → BLOCKED. For each missing skill, choose a\nresolution:\n\n| Resolution | When to Use | Action |\n|---|---|---|\n| **MIGRATE** | Skill is essential to the agent's core workflow | Invoke `$migrate-to-codex` for this skill BEFORE continuing agent migration |\n| **SUBSTITUTE** | A similar Codex skill covers the same domain | Map to the substitute in References, document the rationale |\n| **DROP** | Skill is deprecated, merged, or redundant with agent body content | Omit from References, document the rationale |\n\nPresent the dependency table to the user with recommended resolutions. Only\nproceed to Step 2 after all missing skills are resolved (migrated, substituted,\nor explicitly dropped).\n\n**Example resolution table:**\n\n| Missing Skill | Recommendation | Rationale |\n|---|---|---|\n| `example-url-validator` | SUBSTITUTE → `developing-website-features` | URL validation rules are covered in agent body Constraints section |\n| `example-feature-implementation` | SUBSTITUTE → `integration-testing` | Testing patterns overlap; fullstack patterns are in companion ref |\n\n**Batch migration note**: When migrating `--all`, run Step 1c across ALL agents\nfirst to collect the full set of missing skills. Migrate missing skills in one\nbatch before starting any agent migrations. This prevents redundant skill\nmigrations when multiple agents share the same dependency.\n\n## Step 2: Map Fields\n\nApply the field mapping from\n[agent-field-mapping.md](references\u002Fagent-field-mapping.md).\n\n**Key transformations:**\n\n| Claude Field | Codex Section |\n|---|---|\n| `name` | `# Agent: {Title}` |\n| `description` | `## Purpose` |\n| `tools` + `disallowedTools` | `## Recommended Sandbox` + `## Constraints` |\n| `model` + `effort` \u002F `reasoning_effort` \u002F `model_reasoning_effort` | `## Runtime Configuration` |\n| `skills` | `## References` (`.codex\u002Fskills\u002F` paths) |\n| `hooks.Stop` | `## Runtime Configuration` → completion gate |\n| `color`, `permissionMode` | **Dropped** (documented loss) |\n\n**MCP namespace normalization** (automated by script):\n- `example-server-g` config server id → `mcp__example_server_g__*`\n- `chrome-devtools` config server id → `mcp__chrome_devtools__*`\n\n**Skills → References mapping**: All skill dependencies were resolved in Step 1b.\nMap each resolved skill 1:1 to `.codex\u002Fskills\u002F{name}\u002FSKILL.md`. Substituted\nor dropped skills use the resolution documented in Step 1b.\n\n**Runtime hint preservation**: If the Claude source already carries concrete\nCodex runtime hints such as `model = \"gpt-5.4-mini\"` and\n`model_reasoning_effort = \"medium\"`, preserve them in TOML output instead of\ndown-mapping them to legacy advisory prose.\n\n**Body preservation**: Preserve as much Claude agent content as possible. Agent\nspec hard limit: ≤1000 lines. Extract to\n`.codex\u002Fagents\u002Freferences\u002F{name}-domain.md` only if exceeding the limit.\n\n## Step 2.6: Convert Embedded Delegation Sites\n\nIf the source agent or its companion references contain embedded delegation\nsites, apply the decision process in\n[subagent-migration-guide.md](references\u002Fsubagent-migration-guide.md).\n\nDecision rules:\n\n- Reusable named role → create `.codex\u002Fagents\u002F\u003Cname>.toml`\n- One-off workflow-local prompt slice → keep inline via `spawn_agent(...)`\n- Thin proxy around one MCP call → usually keep inline\n- Routing table with several named roles → every reachable role must have a\n  real Codex agent file before the migration is considered complete\n\nModel guidance:\n\n- Use the intent-based mapping in\n  [subagent-migration-guide.md](references\u002Fsubagent-migration-guide.md) Section 2.\n- Treat that table as this migration package's policy informed by Codex runtime\n  guidance, not as an official OpenAI Claude-to-Codex table.\n\nFormat note:\n\n- File-backed custom agents should use `--format toml`.\n- Markdown output remains valid for compatibility, but it is not the preferred\n  target for new reusable sub-agent roles.\n\n## Step 2.5: Verify Domain Content (Tier 2-3 only)\n\n**WHY THIS STEP EXISTS**: Claude agent bodies drift from the codebase. Route\nconstants get renamed, helper functions get deleted, test infrastructure gets\nreplaced. If you copy stale domain examples into the companion reference,\nthe Codex audit will catch them — but at the cost of an extra audit cycle\n(~500K-1.5M tokens). Verify first, write once.\n\n**For every code example, symbol, path, or config pattern in the Claude agent\nbody**, verify against the live codebase before including in the Codex output:\n\n| Content Type | Verification Method |\n|---|---|\n| Configuration constants (`EXAMPLE_CONSTANTS.*`) | `grep -n \"EXAMPLE_\" example-project\u002Fsrc\u002Fconfig\u002Fsettings.config.ts` |\n| Helper function names | `grep -rn \"functionName(\" path\u002Fto\u002Fmodule\u002F` |\n| Directory paths (`locales\u002F`, `i18n\u002F`) | `ls path\u002Fto\u002Fdirectory\u002F` |\n| Locale directory aliases | Check actual directory names |\n| Router meta patterns (`meta.role` vs `meta.roles`) | `grep -n \"meta.*role\" example-project\u002Fsrc\u002Frouter\u002F` |\n| Test infrastructure (stub dependency vs real dependency) | Read test setup files: `example-project\u002Ftests\u002Ffixtures\u002F` |\n| MCP tools referenced | Check `config.toml` entries |\n\n**Decision rule**: If a code example can't be verified in \u003C30 seconds, replace\nit with a neutral description (e.g., \"use the module's existing pattern\") rather\nthan copying potentially stale specifics. The companion reference should be\n*accurate* over *detailed*.\n\n**Skip for Tier 1**: Mechanical agents have no domain examples to verify.\n\n## Step 3: Execute Migration\n\n### Tier 1 (Mechanical)\n\n```bash\npython3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Fmigrate_claude_agents_to_codex.py --agent \u003Cagent_name>\n```\n\nOutput is structurally complete, but it is not final on write alone. Record a\nmanual nativeness review before treating the generated agent as native.\n\n### Tier 2 (Assisted)\n\n```bash\npython3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Fmigrate_claude_agents_to_codex.py --agent \u003Cagent_name> --format toml\n```\n\nScript output contains `[REVIEW: ...]` annotations. Review:\n- MCP preflight status: confirm project `.codex\u002Fconfig.toml` satisfied all\n  required top-level MCP servers before write mode\n- Sandbox recommendation: confirm matches agent's access pattern\n- Knowledge Priority ordering: adjust for agent's actual tool preference\n- `initialPrompt` → Initial Action conversion: verify prose is accurate\n\n### Tier 3 (Hand-Authored)\n\n```bash\npython3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Fmigrate_claude_agents_to_codex.py --agent \u003Cagent_name> --format toml\n```\n\nScript generates a skeleton with `[TODO: hand-author]` placeholders.\n\n1. Read a representative migrated agent artifact under `.codex\u002Fagents\u002F`\n2. Read template: [codex-agent-template.md](references\u002Fcodex-agent-template.md)\n3. Fill domain sections manually (keep ≤40 lines each)\n4. Extract verbose content to `.codex\u002Fagents\u002Freferences\u002F{name}-domain.md`\n5. For orchestrator roles: restructure Supervisor Pattern per\n   [architectural-patterns.md](references\u002Farchitectural-patterns.md) Pattern 4 + 6\n\n### Batch Mode\n\n```bash\npython3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Fmigrate_claude_agents_to_codex.py --all --format toml\n```\n\nProcesses all agents. Preflight MCP dependencies → assess → migrate by tier →\nreport.\n\n## Step 4: Validate\n\n### Automated Checks\n\nNative Codex output is TOML. Use markdown-only checks only when you explicitly\nrequest `--format md`.\n\n```bash\n# Markdown compatibility output only:\n# 1. No frontmatter delimiters (line 1 must NOT be --- or +++)\nhead -1 .codex\u002Fagents\u002F{name}.md | grep -Ev '^(---|\\+\\+\\+)$'\n\n# 2. No Claude primitives or hyphenated MCP namespaces\npython3 tools\u002Fmigration_support\u002Fvalidate_names.py --scan-dir .codex\u002Fagents\u002F\n\n# 3. Required sections present\ngrep -c '## Purpose\\|## Constraints\\|## Output Contract' .codex\u002Fagents\u002F{name}.md\n\n# 4. Under 1000 lines (hard limit)\nwc -l .codex\u002Fagents\u002F{name}.md\n\n# 5. Starts with # Agent:\nhead -1 .codex\u002Fagents\u002F{name}.md | grep '^# Agent:'\n```\n\n```bash\n# Native TOML output:\n# 1. Valid TOML syntax\npython3 - \u003C\u003C'PY'\nfrom pathlib import Path\nimport tomllib\ntomllib.loads(Path(\".codex\u002Fagents\u002F{name}.toml\").read_text(encoding=\"utf-8\"))\nprint(\"OK\")\nPY\n\n# 2. Required keys present\npython3 - \u003C\u003C'PY'\nfrom pathlib import Path\nimport tomllib\ndata = tomllib.loads(Path(\".codex\u002Fagents\u002F{name}.toml\").read_text(encoding=\"utf-8\"))\nrequired = [\"name\", \"description\", \"developer_instructions\"]\nmissing = [key for key in required if not data.get(key)]\nassert not missing, f\"Missing keys: {missing}\"\nprint(\"OK\")\nPY\n\n# 3. No Claude primitives or hyphenated MCP namespaces in developer instructions\npython3 tools\u002Fmigration_support\u002Fvalidate_names.py --scan-dir .codex\u002Fagents\u002F\n```\n\n### Tier 2 Manual Checklist\n\n- [ ] MCP preflight passed against project `.codex\u002Fconfig.toml`\n- [ ] Sandbox recommendation matches agent's access pattern\n- [ ] Knowledge Priority reflects actual tool preference\n- [ ] Skills referenced exist in `.codex\u002Fskills\u002F`\n- [ ] No `[REVIEW: ...]` annotations remain\n\n### Tier 3 Manual Checklist (adds)\n\n- [ ] Companion reference file created and referenced\n- [ ] Hooks mapped to completion gate in Runtime Configuration\n- [ ] Orchestration patterns (example-agent-m) restructured\n- [ ] No absolute file paths leaked through\n- [ ] No `[TODO: ...]` placeholders remain\n- [ ] Domain sections ≤40 lines each\n\n## Step 5: Native Codex Compliance Audit (inline native sub-agent)\n\n**When**: After Step 4 validation passes — before reporting to the user.\n\n**Review-only entry**: If an agent already exists under `.codex\u002Fagents\u002F` and\nthe tracker says it is `pending_native_review`, this step may be invoked\ndirectly as a read-only single-agent review flow. In that entry path, audit\nfirst, present findings plus next actions, and auto-record `native` by default\nwhen the final audit result is `NO_FINDINGS` unless the user explicitly asked\nfor audit-only behavior.\n\nDashboard routing note:\n\n- `migration-dashboard` may use this review-only entry as a bounded Verify\n  phase after `review next`, `review \u003Cnumber>`, or `review \u003Cname>`.\n- In that entry path, the parent dashboard remains a thin router. This skill\n  owns the reviewer prompt, delegated lifecycle, review-report guidance, and\n  tracker close-out instructions.\n- Shared nativeness handoff helpers live in\n  `tools\u002Fmigration_support\u002F`; workflow\n  scripts bootstrap that package before importing shared migration-family\n  helpers.\n\n**Tracker close-out**: For a clean review, record the outcome automatically with:\n\n- `python3 tools\u002Fmigration_support\u002Ftracker.py --write --record-review agent:\u003Cname>=native`\n- `python3 tools\u002Fmigration_support\u002Ftracker.py --write --record-review agent:\u003Cname>=codex_compatible_but_not_native`\n\nUse the `native` path by default when the final audit or convergence result is\n`NO_FINDINGS`, attaching summary `No findings after convergence`. Keep manual\nclose-out only when MEDIUM findings remain, when the user requested audit-only\nbehavior, or when the tracker write fails. Do not leave the tracker at\n`pending_native_review` after a clean nativeness audit.\n\n**Purpose**: The migrated agent must pass as a **native Codex sub-agent** — not\na ported Claude artifact. A format-correct file that still thinks in Claude\nprimitives, references `.claude\u002F` paths, or assumes Claude-only tools is a\nfailed migration regardless of validation results. GPT-5.4 running as an\ninline native sub-agent audits from inside the Codex ecosystem, judging\nwhether it would accept these agents as its own peers.\n\n**MANDATORY**: Step 5 MUST use inline `spawn_agent(...)` — **NEVER**\n`external Codex review proxy` or `external large-context reviewer`. Only the Codex ecosystem model\n(GPT-5.4) can judge whether an agent reads as a native Codex sub-agent. Gemini\ncannot assess Codex nativeness.\n\n### 5a. Compliance Audit\n\nSpawn one inline nativeness-audit sub-agent with `model: \"gpt-5.4\"` and\n`reasoning_effort: \"high\"`. Keep this agent alive for the entire Step 5 loop.\nThe parent workflow remains the only writer; the auditor stays read-only.\n\nWorkflow contract for this skill:\n\n1. Spawn the auditor once with the full first-pass audit prompt\n2. `wait_agent({\"targets\": [agent.id]})` for findings\n3. Parent applies fixes locally\n4. Reuse the same live auditor via `send_input(...)` for convergence\n5. `wait_agent({\"targets\": [agent.id]})` again\n6. `close_agent(...)` once Step 5 completes or escalates\n\nRationale for the legacy feature choices in this workflow:\n\n- Adopt: `send_input(...)`, `close_agent(...)`\n- Keep as-is: `model`, `reasoning_effort`\n- Defer: `fork_context`, structured `items`, `resume_agent(...)`\n- Avoid here: `send_input(interrupt=true)`\n\nSee\n[legacy-subagent-roi.md](references\u002Flegacy-subagent-roi.md)\nfor the feature-by-feature ROI table.\n\nExample shape:\n\n```\nagent = spawn_agent({\n  agent_type: \"default\",\n  model: \"gpt-5.4\",\n  reasoning_effort: \"high\",\n  message: `You are a Codex ecosystem compliance auditor.\n\n  This is a READ-ONLY audit.\n  - Do not edit files\n  - Do not call apply_patch\n  - Do not rerun migration scripts\n  - Verify paths and symbols through read-only inspection when the runtime permits\n\n  ${dynamicAuditPrompt}`\n})\nresult = wait_agent({\"targets\": [agent.id]})\n```\n\n**Prompt** (substitute `{MIGRATED}`, `{SOURCES}` with actual absolute paths):\n\n```\nYou are a Codex ecosystem compliance auditor. Your job: determine whether\neach migrated agent file would pass as a NATIVE Codex sub-agent — as if it\nwas designed for Codex from day one, not ported from another system.\n\nThis is a READ-ONLY audit.\n- Do not edit files\n- Do not call apply_patch\n- Do not rerun migration scripts\n- Verify paths and symbols through read-only inspection when the runtime permits\n\nREAD FIRST (gold standard): {reference migrated agent artifact under .codex\u002Fagents\u002F}\nREAD NEXT (Codex MCP config): .codex\u002Fconfig.toml\nTHEN READ each migrated file and its Claude source side by side:\n\nMIGRATED: {MIGRATED}\nSOURCES:  {SOURCES}\n\nAUDIT DIMENSIONS (ordered by severity):\n\nCRITICAL — Ecosystem incompatibility:\n- Frontmatter delimiters present (Codex markdown agents are pure markdown)\n- References old tool or primitive spellings that don't exist in Codex\n- MCP config server ids are used directly as callable namespaces instead of underscore-normalized names (`example-server-g` config id → `mcp__example_server_g__`)\n- References .claude\u002F paths instead of .codex\u002F paths\n- Absolute \u002FUsers\u002F... paths leaked through\n\nHIGH — Semantic fidelity:\n- Purpose section lost the agent's core responsibility vs Claude source\n- The agent's execution contract was not re-expressed in Codex sub-agent terms and instead was flattened into a generic helper, losing operational role, decision boundaries, or constraint model\n- Safety-critical constraints dropped or weakened during migration (especially test guardrails, zero-mocking stances, cleanup lifecycle rules)\n- Hard constraints softened during compression: MUST\u002FNEVER\u002FONLY language becomes suggestions. Compare constraint strength between source and target — hard rules must survive verbatim\n- MCP servers referenced but missing from .codex\u002Fconfig.toml\n- Skill paths referenced but don't exist under .codex\u002Fskills\u002F\n- Companion reference files referenced but missing on disk\n\nHIGH — Domain accuracy (VERIFY AGAINST LIVE CODEBASE):\nClaude agent bodies drift from the codebase. Every code example, route\nconstant, helper function name, directory path, router meta pattern, and\ntest infrastructure detail in the migrated files is an implicit assertion.\nVerify these against the actual repo with read-only inspection when the runtime permits:\n- Configuration constants: grep the routes config file for the exact symbol name\n- Directory paths: inspect the actual directory (e.g., locales\u002F vs i18n\u002F, source-locale vs target-locale)\n- Helper functions: grep for the function name in the relevant module\n- Router meta patterns: read the actual router file (singular role vs roles array)\n- Test infrastructure: check actual test setup files (stub dependency vs real dependency)\n- API service names: grep for the class name to confirm it exists\nIf an example references something that doesn't exist in the live codebase,\nthat is a HIGH finding — a sub-agent copying it will produce broken code.\n\nMEDIUM — Nativeness quality:\n- Agent reads as a translation rather than a native spec (Claude jargon, hedging language about \"in Codex this would be...\")\n- Knowledge Priority doesn't reflect actual Codex tool availability\n- Sandbox recommendation mismatches agent's access pattern\n- Leftover [REVIEW:] or [TODO:] annotations\n- Sections exceed 40 lines (should extract to companion ref)\n\nOUTPUT (per finding):\n  SEVERITY: {CRITICAL|HIGH|MEDIUM}\n  FILE: {path}\n  ISSUE: {one-line}\n  FIX: {concrete instruction}\n\nIf clean: \"NO_FINDINGS\"\nEnd with: \"AUDIT_COMPLETE\"\n```\n\n### 5b. Auto-Address Findings\n\nParse audit output. For each finding:\n\n- **CRITICAL\u002FHIGH** — Fix immediately via Edit tool. Surgical edits only — do\n  NOT re-run the migration script.\n- **MEDIUM** — Fix if mechanical. Flag to user only if the fix requires judgment.\n\nDo not spawn a second auditor for fixes. The parent applies fixes, then reuses\nthe same auditor thread for convergence.\n\nFor dashboard-driven review-only entry, keep the parent-thread return compact:\n\n- verdict\n- top findings or `NO_FINDINGS`\n- next action\n- review-report path when available\n\nDo not paste the full audit transcript into the main thread unless the user\nexplicitly asks for it.\n\n### 5c. Convergence Check\n\nReuse the same live nativeness-audit sub-agent via `send_input(...)` for a\nfocused re-audit. Do not respawn the auditor unless the original agent died.\n\n```\nsend_input({\n  target: agent.id,\n  message: `CONVERGENCE CHECK: Previous audit found {N} issues, all addressed.\n\n  This is a READ-ONLY audit.\n  - Do not edit files\n  - Do not call apply_patch\n  - Do not rerun migration scripts\n  - Verify paths and symbols through read-only inspection when the runtime permits\n\n  Re-read these files and verify:\n  1. Previous findings resolved\n  2. No new CRITICAL\u002FHIGH issues introduced by fixes\n  3. Each agent still reads as a native Codex sub-agent\n\n  FILES: {paths that had findings}\n  GOLD STANDARD: {reference migrated agent artifact under .codex\u002Fagents\u002F}\n\n  Same output format. \"NO_FINDINGS\" if clean. End with \"AUDIT_COMPLETE\".`\n})\nresult = wait_agent({\"targets\": [agent.id]})\n```\n\nIf the initial audit already returned `NO_FINDINGS`, skip convergence, record\n`native` by default, and close the auditor immediately unless the user asked\nfor audit-only behavior.\n\n### 5d. Convergence Decision\n\nNative completion rule:\n\n- The agent's execution contract must be re-expressed in Codex sub-agent terms without flattening its original operational role, decision boundaries, or constraint model. If the file is format-correct but semantically flattened, do not declare it native.\n\n| Result | Action |\n|---|---|\n| `NO_FINDINGS` | Auto-record `native`, then proceed to Step 6 |\n| Only MEDIUM | Proceed to Step 6, note as \"Acknowledged minor items\" |\n| Any CRITICAL\u002FHIGH | **STOP** — escalate to user. Do not declare complete. |\n\n**Hard cap**: 2 cycles (audit + convergence). Persistent critical issues =\nsystemic problem requiring human judgment.\n\nLifecycle rule:\n\n- Always `close_agent({ target: agent.id })` before leaving Step 5, whether the\n  result is success, acknowledged-medium, or escalation.\n- Save the full nativeness review to a markdown report when the review is\n  meant to be recorded later. Reuse the existing agent-migration report\n  directories or an explicit `\u002Ftmp` review path, then attach that path through\n  `--review-evidence` at tracker close-out.\n\n## Step 6: Report\n\n### Single Agent\n\n```\nMigration Report: {name}\n  Tier: {1|2|3}\n  Source: .claude\u002Fagents\u002F{name}.md ({N} lines)\n  Target: .codex\u002Fagents\u002F{name}.toml ({M} lines)\n  Companion: .codex\u002Fagents\u002Freferences\u002F{name}-domain.md (if extracted)\n  Status: {COMPLETE|REVIEW_NEEDED|SKELETON_GENERATED|ALREADY_MIGRATED}\n  Sandbox: {read-only|workspace-write}\n  Validation: {PASS|FAIL (details)}\n  Codex Compliance: {NATIVE (0 findings)|NATIVE ({N} fixed)|ESCALATED (details)}\n  Fields mapped: {list}\n  Fields dropped: {list with reason}\n  Remaining gaps: {items needing attention}\n```\n\n### Batch Summary\n\nTable of migrated agents with tier, status, and validation result.\n\n## Migration Order\n\nWhen migrating all agents, process in this order:\n\n1. **example-agent-a** (Tier 1) — simplest, validates the pipeline\n2. **example-agent-i, example-agent-l, example-agent-j, example-agent-k** (Tier 2)\n3. **example-agent-h, example-agent-g** (Tier 2, borderline complexity)\n4. **example-agent-c, example-agent-f** (Tier 3, companion ref extraction)\n5. **example-agent-d, example-agent-e** (Tier 3, MCP gap resolution needed)\n6. **example-agent-m** (Tier 3, LAST — depends on all leaf agents being stable)\n\n## Anti-Patterns\n\n| Don't | Do Instead |\n|---|---|\n| Preserve frontmatter delimiters | Strip frontmatter, map to markdown sections |\n| Exceed 1000 lines | Extract verbose domain content to companion refs |\n| Convert hooks to comments | Map to completion gate in Runtime Configuration |\n| Map `tools` to a \"Tools\" section | Use Constraints + Recommended Sandbox sections |\n| Keep absolute `\u002FUsers\u002F...` paths | Strip to repo-relative paths |\n| Mechanical conversion on Tier 3 | Generate skeleton, hand-author domain sections |\n| Use fabricated Codex primitives | Verify against official Codex docs |\n| Skip compliance audit for \"simple\" agents | Always run — even T1 agents can have namespace drift |\n| Let the nativeness auditor edit files directly | Keep the auditor read-only by prompt contract — parent workflow applies fixes |\n| Loop audit >2 cycles | Escalate to user after convergence if CRITICAL remains |\n| Report completion before audit passes | Step 5 must gate Step 6 |\n| Treat format-correct as native-compliant | A file can pass validation but still read as a port |\n| Trust Claude agent body as accurate | Agent bodies drift — verify domain examples against live codebase (Step 2.5) |\n| Substitute or drop missing skills silently | Treat missing skills as a blocker — resolve via MIGRATE\u002FSUBSTITUTE\u002FDROP in Step 1b |\n| Copy code examples verbatim from Claude source | Every route constant, helper name, meta pattern is an assertion — grep to confirm |\n| Weaken safety constraints during compression | Preserve hard rules verbatim: \"preserve setup boundaries\", \"preserve integration constraints\", \"preserve test-scope constraints\" |\n| Use port-artifact language in companion files | \"Extracted during Codex migration\" → \"Reference for X agent. Use when Y.\" |\n\n## Migration Review Guidance\n\n**Rationale**: Migration audits often find\nformat issues and stale source knowledge\ncarried over from the Claude agent body.\n\n**Key patterns:**\n1. **Claude agent bodies are NOT authoritative** — they're cached snapshots of\n   codebase knowledge. Configuration constants get renamed, test infrastructure gets\n   replaced, helpers get deleted. Step 2.5 exists to catch this BEFORE writing.\n2. **Companion references are assertion-dense** — every code example is a claim\n   about codebase state. More specific = more fragile. When in doubt, use\n   neutral descriptions (\"use the module's existing pattern\") over stale specifics.\n3. **The initial audit catches ecosystem issues; convergence catches domain\n   drift** — this asymmetry is by design now. The initial audit prompt includes\n   \"Domain accuracy: VERIFY AGAINST LIVE CODEBASE\" to push more domain checks\n   into the first cycle, reducing convergence-cycle findings and token cost.\n4. **Unmigrated skill references are invisible until audit** — `ls .codex\u002Fskills\u002F`\n   takes 1 second but saves an entire audit finding + fix cycle.\n5. **Specific constraints need review** — \"real dependencies over simplified fixtures\" is\n   not the same rigor as \"specific external dependency requirements — no lightweight stand-ins, no\n   simplified fixtures.\" Keep the actionable requirement clear.\n\n## Shared References\n\nThese references are symlinked from the sibling `migrate-to-codex` skill:\n\n- [primitive-mapping.md](references\u002Fprimitive-mapping.md) — Claude→Codex tool mapping\n- [architectural-patterns.md](references\u002Farchitectural-patterns.md) — 6 migration patterns\n\nAgent-specific references:\n\n- [agent-complexity-classifier.md](references\u002Fagent-complexity-classifier.md) — Tier decision tree\n- [agent-field-mapping.md](references\u002Fagent-field-mapping.md) — Frontmatter→section mapping\n- [codex-agent-template.md](references\u002Fcodex-agent-template.md) — Gold standard template\n- [legacy-subagent-roi.md](references\u002Flegacy-subagent-roi.md) — Which legacy\n  sub-agent features are worth using in this migration workflow\n","\u003C!-- Generated by the ccode-to-codex mirror sync on 2026-04-14 from input revision 9a2403fb. -->\n# Migrate Agents to Codex\n\n## Purpose\n\nMigrates Claude agent definitions from `.claude\u002Fagents\u002F*.md` (YAML frontmatter\n+ markdown body) to Codex-compatible outputs under `.codex\u002Fagents\u002F`.\n\nPreferred output: standalone TOML custom-agent files.\nBackward-compatible output only: pure-markdown behavioral specifications.\n\nThe migration strips frontmatter, maps fields to native Codex contracts,\npreserves runtime hints such as `model`, `effort`, `reasoning_effort`, and\n`model_reasoning_effort`, normalizes MCP namespaces, and extracts large domain\ncontent into companion reference files.\n\nAfter migration, a **native Codex compliance audit** (GPT-5.4 inline\nsub-agent) validates every migrated file passes as a native Codex sub-agent —\nnot a ported Claude artifact. Mechanical output is never final on write alone:\nevery mechanically generated agent requires a recorded manual nativeness review\nbefore it may be treated as native. Findings are auto-addressed and a\nconvergence check confirms no regressions were introduced by the fixes.\n\nPipeline position: **CODE → VERIFY** (runs during implementation phase).\nCovers 2 stages: CODE (migration) + VERIFY (adversarial review loop).\n\nCanonical conversation wrapper:\n`.codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Frun_agent_migration_workflow.py`\nDeterministic engine:\n`.codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Fmigrate_claude_agents_to_codex.py`\n\n## Conversation-First Entry\n\nBare requests should start with a user-facing action menu, not a wall of CLI\nflags. Follow the shared contract in\n`..\u002Fmigrate-to-codex\u002Freferences\u002Fconversational-migration-contract.md`.\n\nDefault menu for underspecified requests:\n\n1. Assess one agent\n2. Preview one agent as TOML\n3. Migrate one agent live\n4. Batch preflight all agents\n5. Review one migrated agent for nativeness\n6. Explain MCP or skill blockers\n\nRouting rules:\n\n- If the user already says `preview example-agent-e`, `migrate example-agent-c`,\n  or `review example-agent-e`, route directly.\n- In Plan mode, use `request_user_input` only for the action choice.\n- Outside Plan mode, render the same action set as a numbered text menu.\n- If the action still needs an agent name, ask for it in plain text.\n- Require explicit confirmation before any live write into `.codex\u002Fagents\u002F` or\n  any `--force` overwrite.\n\n## Advanced CLI\n\n- Preferred wrappers:\n  - `python3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Fmigrate_claude_agents_to_codex.py --agent example-agent-a --dry-run --json`\n  - `python3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Frun_agent_migration_workflow.py --preview --agent example-agent-a --json`\n  - `python3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Frun_agent_migration_workflow.py --agent example-agent-a --json`\n- Power-user engine:\n  - `python3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Fmigrate_claude_agents_to_codex.py --all --format toml`\n\n## Prerequisites\n\n- Python 3.11+ available\n- Sibling skill exists: `.codex\u002Fskills\u002Fmigrate-to-codex\u002F` (provides shared functions)\n- `.codex\u002Fagents\u002F` directory will be created by the script if missing\n- `.codex\u002Fconfig.toml` exists with MCP server definitions\n- Gold standard reference if present: a previously migrated agent artifact under\n  `.codex\u002Fagents\u002F`\n- Shared conversation contract available at\n  `..\u002Fmigrate-to-codex\u002Freferences\u002Fconversational-migration-contract.md`\n\n## Format: Markdown vs TOML\n\nOfficial Codex custom-agent format is TOML under `.codex\u002Fagents\u002F*.toml`.\n\nUse:\n\n- `--format toml` for new migrations\n- `--format md` only for backward-compatible markdown outputs\n\nRules:\n\n- If both `.md` and `.toml` exist for the same agent, treat `.toml` as the\n  runtime-preferred artifact.\n- Markdown remains useful as documentation and as a bridge for older migration\n  runs, but new custom agents should default to TOML.\n- Validation must branch by format. A TOML migration is not complete if the\n  workflow still validates only markdown headings.\n\n## Step 1: Assess Complexity & Resolve Dependencies\n\n**Context**: User provides an agent name, a list, `--all`, or a bare request\nthat still needs the menu\u002Ffront-door routing.\n\nBefore running the backend:\n\n- bare request -> show the family menu from the shared conversational contract\n- explicit action + explicit target -> route directly\n- explicit action + missing target -> ask for the target name\n- explicit `review \u003Cagent>` on an already migrated agent -> skip migration\n  write logic and jump to Step 5 as a read-only nativeness audit\n- live migration -> require confirmation before the write step\n\n### 1a. Classify\n\nClassify each target agent using the decision tree in\n[agent-complexity-classifier.md](references\u002Fagent-complexity-classifier.md).\n\nRun the assessment path through the backend wrapper or execute directly:\n\n```bash\npython3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Frun_agent_migration_workflow.py --preview --agent example-agent-a --json\npython3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Fmigrate_claude_agents_to_codex.py --all --dry-run --json\n```\n\nThe script parses each `.claude\u002Fagents\u002F*.md`, extracts frontmatter, counts\nMCP tools, detects hooks\u002Forchestration patterns, and outputs a classification\ntable with tier, readiness score, sandbox recommendation, dependency blockers,\nand next actions.\n\n**Skip rules:**\n- Agents with existing native `.codex\u002Fagents\u002F{name}.toml` or legacy\n  `.codex\u002Fagents\u002F{name}.md`\n  → SKIP (validate only)\n- Use `--force` to overwrite existing agents\n\n**Classification output:**\n\nUse generated classification output from the current input batch. Do not hard-code source-agent rosters in this skill.\n\n\n### 1b. MCP Dependency Preflight\n\nBefore resolving skill dependencies or writing any migrated agent, run an MCP\ndependency preflight against the project-level `.codex\u002Fconfig.toml`.\n\nRules:\n\n- Source of truth is the Claude agent frontmatter `tools:` list only.\n- Extract required MCP servers only from tools matching\n  `mcp__\u003Cserver>__\u003Ctool>`.\n- Treat `ide` as a Claude-only built-in integration, not a project MCP\n  dependency. Record it as unsupported source tooling and drop it from migrated\n  agent dependency requirements.\n- Normalize server ids to project config-key form before comparison\n  (`example_server_g` → `example-server-g`, `chrome_devtools` → `chrome-devtools`).\n- Read only top-level `[mcp_servers.\u003Cid>]` entries from `.codex\u002Fconfig.toml`.\n  Nested tables such as `[mcp_servers.\u003Cid>.tools.*]` do not count as separate\n  servers.\n- Agent-local output must not synthesize `[mcp_servers.*]` stanzas. Missing\n  server config is resolved only by editing project `.codex\u002Fconfig.toml`.\n\nBlocker behavior:\n\n- `--agent \u003Cname> --dry-run`: always print required\u002Fconfigured\u002Fmissing MCP\n  servers and preview the generated output.\n- `--agent \u003Cname>` in write mode: if `missing_mcp_servers` is non-empty, print\n  a blocker report, write nothing, and exit non-zero.\n- `--all --dry-run`: report MCP status for every agent, including all blocked\n  agents and their missing servers.\n- `--all` in write mode: preflight the full batch first. If any target agent is\n  blocked, write nothing for the whole batch and exit non-zero.\n\nSource-specific dependency notes:\n\n- Treat unsupported source tooling such as `ide` as input data, not as an MCP blocker.\n- Do not hard-code the current repository's agent roster or dependency state into public guidance.\n\n\n### 1c. Resolve Skill Dependencies\n\nFor each agent being migrated, cross-reference its `skills:` frontmatter\nagainst what exists in `.codex\u002Fskills\u002F`:\n\n```bash\n# Extract skills from Claude agent\ngrep '^  - ' .claude\u002Fagents\u002F{name}.md | sed 's\u002F^  - \u002F\u002F'\n\n# Check which exist in Codex\nls .codex\u002Fskills\u002F\n```\n\nProduce a dependency table:\n\n```\nAgent: \u003Cexample role> (Tier 3)\nSkills: 5 declared, 3 available, 2 MISSING\n  ✅ api-proxy-pattern-example              → .codex\u002Fskills\u002Fapi-proxy-pattern-example\u002FSKILL.md\n  ✅ frontend-interaction-example  → .codex\u002Fskills\u002Ffrontend-interaction-example\u002FSKILL.md\n  ✅ api-contracts-example          → .codex\u002Fskills\u002Fapi-contracts-example\u002FSKILL.md\n  ❌ example-url-validator             → NOT IN .codex\u002Fskills\u002F\n  ❌ example-feature-implementation → NOT IN .codex\u002Fskills\u002F\n```\n\n**If all skills are available** → READY. Proceed to Step 2.\n\n**If any skills are missing** → BLOCKED. For each missing skill, choose a\nresolution:\n\n| Resolution | When to Use | Action |\n|---|---|---|\n| **MIGRATE** | Skill is essential to the agent's core workflow | Invoke `$migrate-to-codex` for this skill BEFORE continuing agent migration |\n| **SUBSTITUTE** | A similar Codex skill covers the same domain | Map to the substitute in References, document the rationale |\n| **DROP** | Skill is deprecated, merged, or redundant with agent body content | Omit from References, document the rationale |\n\nPresent the dependency table to the user with recommended resolutions. Only\nproceed to Step 2 after all missing skills are resolved (migrated, substituted,\nor explicitly dropped).\n\n**Example resolution table:**\n\n| Missing Skill | Recommendation | Rationale |\n|---|---|---|\n| `example-url-validator` | SUBSTITUTE → `developing-website-features` | URL validation rules are covered in agent body Constraints section |\n| `example-feature-implementation` | SUBSTITUTE → `integration-testing` | Testing patterns overlap; fullstack patterns are in companion ref |\n\n**Batch migration note**: When migrating `--all`, run Step 1c across ALL agents\nfirst to collect the full set of missing skills. Migrate missing skills in one\nbatch before starting any agent migrations. This prevents redundant skill\nmigrations when multiple agents share the same dependency.\n\n## Step 2: Map Fields\n\nApply the field mapping from\n[agent-field-mapping.md](references\u002Fagent-field-mapping.md).\n\n**Key transformations:**\n\n| Claude Field | Codex Section |\n|---|---|\n| `name` | `# Agent: {Title}` |\n| `description` | `## Purpose` |\n| `tools` + `disallowedTools` | `## Recommended Sandbox` + `## Constraints` |\n| `model` + `effort` \u002F `reasoning_effort` \u002F `model_reasoning_effort` | `## Runtime Configuration` |\n| `skills` | `## References` (`.codex\u002Fskills\u002F` paths) |\n| `hooks.Stop` | `## Runtime Configuration` → completion gate |\n| `color`, `permissionMode` | **Dropped** (documented loss) |\n\n**MCP namespace normalization** (automated by script):\n- `example-server-g` config server id → `mcp__example_server_g__*`\n- `chrome-devtools` config server id → `mcp__chrome_devtools__*`\n\n**Skills → References mapping**: All skill dependencies were resolved in Step 1b.\nMap each resolved skill 1:1 to `.codex\u002Fskills\u002F{name}\u002FSKILL.md`. Substituted\nor dropped skills use the resolution documented in Step 1b.\n\n**Runtime hint preservation**: If the Claude source already carries concrete\nCodex runtime hints such as `model = \"gpt-5.4-mini\"` and\n`model_reasoning_effort = \"medium\"`, preserve them in TOML output instead of\ndown-mapping them to legacy advisory prose.\n\n**Body preservation**: Preserve as much Claude agent content as possible. Agent\nspec hard limit: ≤1000 lines. Extract to\n`.codex\u002Fagents\u002Freferences\u002F{name}-domain.md` only if exceeding the limit.\n\n## Step 2.6: Convert Embedded Delegation Sites\n\nIf the source agent or its companion references contain embedded delegation\nsites, apply the decision process in\n[subagent-migration-guide.md](references\u002Fsubagent-migration-guide.md).\n\nDecision rules:\n\n- Reusable named role → create `.codex\u002Fagents\u002F\u003Cname>.toml`\n- One-off workflow-local prompt slice → keep inline via `spawn_agent(...)`\n- Thin proxy around one MCP call → usually keep inline\n- Routing table with several named roles → every reachable role must have a\n  real Codex agent file before the migration is considered complete\n\nModel guidance:\n\n- Use the intent-based mapping in\n  [subagent-migration-guide.md](references\u002Fsubagent-migration-guide.md) Section 2.\n- Treat that table as this migration package's policy informed by Codex runtime\n  guidance, not as an official OpenAI Claude-to-Codex table.\n\nFormat note:\n\n- File-backed custom agents should use `--format toml`.\n- Markdown output remains valid for compatibility, but it is not the preferred\n  target for new reusable sub-agent roles.\n\n## Step 2.5: Verify Domain Content (Tier 2-3 only)\n\n**WHY THIS STEP EXISTS**: Claude agent bodies drift from the codebase. Route\nconstants get renamed, helper functions get deleted, test infrastructure gets\nreplaced. If you copy stale domain examples into the companion reference,\nthe Codex audit will catch them — but at the cost of an extra audit cycle\n(~500K-1.5M tokens). Verify first, write once.\n\n**For every code example, symbol, path, or config pattern in the Claude agent\nbody**, verify against the live codebase before including in the Codex output:\n\n| Content Type | Verification Method |\n|---|---|\n| Configuration constants (`EXAMPLE_CONSTANTS.*`) | `grep -n \"EXAMPLE_\" example-project\u002Fsrc\u002Fconfig\u002Fsettings.config.ts` |\n| Helper function names | `grep -rn \"functionName(\" path\u002Fto\u002Fmodule\u002F` |\n| Directory paths (`locales\u002F`, `i18n\u002F`) | `ls path\u002Fto\u002Fdirectory\u002F` |\n| Locale directory aliases | Check actual directory names |\n| Router meta patterns (`meta.role` vs `meta.roles`) | `grep -n \"meta.*role\" example-project\u002Fsrc\u002Frouter\u002F` |\n| Test infrastructure (stub dependency vs real dependency) | Read test setup files: `example-project\u002Ftests\u002Ffixtures\u002F` |\n| MCP tools referenced | Check `config.toml` entries |\n\n**Decision rule**: If a code example can't be verified in \u003C30 seconds, replace\nit with a neutral description (e.g., \"use the module's existing pattern\") rather\nthan copying potentially stale specifics. The companion reference should be\n*accurate* over *detailed*.\n\n**Skip for Tier 1**: Mechanical agents have no domain examples to verify.\n\n## Step 3: Execute Migration\n\n### Tier 1 (Mechanical)\n\n```bash\npython3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Fmigrate_claude_agents_to_codex.py --agent \u003Cagent_name>\n```\n\nOutput is structurally complete, but it is not final on write alone. Record a\nmanual nativeness review before treating the generated agent as native.\n\n### Tier 2 (Assisted)\n\n```bash\npython3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Fmigrate_claude_agents_to_codex.py --agent \u003Cagent_name> --format toml\n```\n\nScript output contains `[REVIEW: ...]` annotations. Review:\n- MCP preflight status: confirm project `.codex\u002Fconfig.toml` satisfied all\n  required top-level MCP servers before write mode\n- Sandbox recommendation: confirm matches agent's access pattern\n- Knowledge Priority ordering: adjust for agent's actual tool preference\n- `initialPrompt` → Initial Action conversion: verify prose is accurate\n\n### Tier 3 (Hand-Authored)\n\n```bash\npython3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Fmigrate_claude_agents_to_codex.py --agent \u003Cagent_name> --format toml\n```\n\nScript generates a skeleton with `[TODO: hand-author]` placeholders.\n\n1. Read a representative migrated agent artifact under `.codex\u002Fagents\u002F`\n2. Read template: [codex-agent-template.md](references\u002Fcodex-agent-template.md)\n3. Fill domain sections manually (keep ≤40 lines each)\n4. Extract verbose content to `.codex\u002Fagents\u002Freferences\u002F{name}-domain.md`\n5. For orchestrator roles: restructure Supervisor Pattern per\n   [architectural-patterns.md](references\u002Farchitectural-patterns.md) Pattern 4 + 6\n\n### Batch Mode\n\n```bash\npython3 .codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Fmigrate_claude_agents_to_codex.py --all --format toml\n```\n\nProcesses all agents. Preflight MCP dependencies → assess → migrate by tier →\nreport.\n\n## Step 4: Validate\n\n### Automated Checks\n\nNative Codex output is TOML. Use markdown-only checks only when you explicitly\nrequest `--format md`.\n\n```bash\n# Markdown compatibility output only:\n# 1. No frontmatter delimiters (line 1 must NOT be --- or +++)\nhead -1 .codex\u002Fagents\u002F{name}.md | grep -Ev '^(---|\\+\\+\\+)$'\n\n# 2. No Claude primitives or hyphenated MCP namespaces\npython3 tools\u002Fmigration_support\u002Fvalidate_names.py --scan-dir .codex\u002Fagents\u002F\n\n# 3. Required sections present\ngrep -c '## Purpose\\|## Constraints\\|## Output Contract' .codex\u002Fagents\u002F{name}.md\n\n# 4. Under 1000 lines (hard limit)\nwc -l .codex\u002Fagents\u002F{name}.md\n\n# 5. Starts with # Agent:\nhead -1 .codex\u002Fagents\u002F{name}.md | grep '^# Agent:'\n```\n\n```bash\n# Native TOML output:\n# 1. Valid TOML syntax\npython3 - \u003C\u003C'PY'\nfrom pathlib import Path\nimport tomllib\ntomllib.loads(Path(\".codex\u002Fagents\u002F{name}.toml\").read_text(encoding=\"utf-8\"))\nprint(\"OK\")\nPY\n\n# 2. Required keys present\npython3 - \u003C\u003C'PY'\nfrom pathlib import Path\nimport tomllib\ndata = tomllib.loads(Path(\".codex\u002Fagents\u002F{name}.toml\").read_text(encoding=\"utf-8\"))\nrequired = [\"name\", \"description\", \"developer_instructions\"]\nmissing = [key for key in required if not data.get(key)]\nassert not missing, f\"Missing keys: {missing}\"\nprint(\"OK\")\nPY\n\n# 3. No Claude primitives or hyphenated MCP namespaces in developer instructions\npython3 tools\u002Fmigration_support\u002Fvalidate_names.py --scan-dir .codex\u002Fagents\u002F\n```\n\n### Tier 2 Manual Checklist\n\n- [ ] MCP preflight passed against project `.codex\u002Fconfig.toml`\n- [ ] Sandbox recommendation matches agent's access pattern\n- [ ] Knowledge Priority reflects actual tool preference\n- [ ] Skills referenced exist in `.codex\u002Fskills\u002F`\n- [ ] No `[REVIEW: ...]` annotations remain\n\n### Tier 3 Manual Checklist (adds)\n\n- [ ] Companion reference file created and referenced\n- [ ] Hooks mapped to completion gate in Runtime Configuration\n- [ ] Orchestration patterns (example-agent-m) restructured\n- [ ] No absolute file paths leaked through\n- [ ] No `[TODO: ...]` placeholders remain\n- [ ] Domain sections ≤40 lines each\n\n## Step 5: Native Codex Compliance Audit (inline native sub-agent)\n\n**When**: After Step 4 validation passes — before reporting to the user.\n\n**Review-only entry**: If an agent already exists under `.codex\u002Fagents\u002F` and\nthe tracker says it is `pending_native_review`, this step may be invoked\ndirectly as a read-only single-agent review flow. In that entry path, audit\nfirst, present findings plus next actions, and auto-record `native` by default\nwhen the final audit result is `NO_FINDINGS` unless the user explicitly asked\nfor audit-only behavior.\n\nDashboard routing note:\n\n- `migration-dashboard` may use this review-only entry as a bounded Verify\n  phase after `review next`, `review \u003Cnumber>`, or `review \u003Cname>`.\n- In that entry path, the parent dashboard remains a thin router. This skill\n  owns the reviewer prompt, delegated lifecycle, review-report guidance, and\n  tracker close-out instructions.\n- Shared nativeness handoff helpers live in\n  `tools\u002Fmigration_support\u002F`; workflow\n  scripts bootstrap that package before importing shared migration-family\n  helpers.\n\n**Tracker close-out**: For a clean review, record the outcome automatically with:\n\n- `python3 tools\u002Fmigration_support\u002Ftracker.py --write --record-review agent:\u003Cname>=native`\n- `python3 tools\u002Fmigration_support\u002Ftracker.py --write --record-review agent:\u003Cname>=codex_compatible_but_not_native`\n\nUse the `native` path by default when the final audit or convergence result is\n`NO_FINDINGS`, attaching summary `No findings after convergence`. Keep manual\nclose-out only when MEDIUM findings remain, when the user requested audit-only\nbehavior, or when the tracker write fails. Do not leave the tracker at\n`pending_native_review` after a clean nativeness audit.\n\n**Purpose**: The migrated agent must pass as a **native Codex sub-agent** — not\na ported Claude artifact. A format-correct file that still thinks in Claude\nprimitives, references `.claude\u002F` paths, or assumes Claude-only tools is a\nfailed migration regardless of validation results. GPT-5.4 running as an\ninline native sub-agent audits from inside the Codex ecosystem, judging\nwhether it would accept these agents as its own peers.\n\n**MANDATORY**: Step 5 MUST use inline `spawn_agent(...)` — **NEVER**\n`external Codex review proxy` or `external large-context reviewer`. Only the Codex ecosystem model\n(GPT-5.4) can judge whether an agent reads as a native Codex sub-agent. Gemini\ncannot assess Codex nativeness.\n\n### 5a. Compliance Audit\n\nSpawn one inline nativeness-audit sub-agent with `model: \"gpt-5.4\"` and\n`reasoning_effort: \"high\"`. Keep this agent alive for the entire Step 5 loop.\nThe parent workflow remains the only writer; the auditor stays read-only.\n\nWorkflow contract for this skill:\n\n1. Spawn the auditor once with the full first-pass audit prompt\n2. `wait_agent({\"targets\": [agent.id]})` for findings\n3. Parent applies fixes locally\n4. Reuse the same live auditor via `send_input(...)` for convergence\n5. `wait_agent({\"targets\": [agent.id]})` again\n6. `close_agent(...)` once Step 5 completes or escalates\n\nRationale for the legacy feature choices in this workflow:\n\n- Adopt: `send_input(...)`, `close_agent(...)`\n- Keep as-is: `model`, `reasoning_effort`\n- Defer: `fork_context`, structured `items`, `resume_agent(...)`\n- Avoid here: `send_input(interrupt=true)`\n\nSee\n[legacy-subagent-roi.md](references\u002Flegacy-subagent-roi.md)\nfor the feature-by-feature ROI table.\n\nExample shape:\n\n```\nagent = spawn_agent({\n  agent_type: \"default\",\n  model: \"gpt-5.4\",\n  reasoning_effort: \"high\",\n  message: `You are a Codex ecosystem compliance auditor.\n\n  This is a READ-ONLY audit.\n  - Do not edit files\n  - Do not call apply_patch\n  - Do not rerun migration scripts\n  - Verify paths and symbols through read-only inspection when the runtime permits\n\n  ${dynamicAuditPrompt}`\n})\nresult = wait_agent({\"targets\": [agent.id]})\n```\n\n**Prompt** (substitute `{MIGRATED}`, `{SOURCES}` with actual absolute paths):\n\n```\nYou are a Codex ecosystem compliance auditor. Your job: determine whether\neach migrated agent file would pass as a NATIVE Codex sub-agent — as if it\nwas designed for Codex from day one, not ported from another system.\n\nThis is a READ-ONLY audit.\n- Do not edit files\n- Do not call apply_patch\n- Do not rerun migration scripts\n- Verify paths and symbols through read-only inspection when the runtime permits\n\nREAD FIRST (gold standard): {reference migrated agent artifact under .codex\u002Fagents\u002F}\nREAD NEXT (Codex MCP config): .codex\u002Fconfig.toml\nTHEN READ each migrated file and its Claude source side by side:\n\nMIGRATED: {MIGRATED}\nSOURCES:  {SOURCES}\n\nAUDIT DIMENSIONS (ordered by severity):\n\nCRITICAL — Ecosystem incompatibility:\n- Frontmatter delimiters present (Codex markdown agents are pure markdown)\n- References old tool or primitive spellings that don't exist in Codex\n- MCP config server ids are used directly as callable namespaces instead of underscore-normalized names (`example-server-g` config id → `mcp__example_server_g__`)\n- References .claude\u002F paths instead of .codex\u002F paths\n- Absolute \u002FUsers\u002F... paths leaked through\n\nHIGH — Semantic fidelity:\n- Purpose section lost the agent's core responsibility vs Claude source\n- The agent's execution contract was not re-expressed in Codex sub-agent terms and instead was flattened into a generic helper, losing operational role, decision boundaries, or constraint model\n- Safety-critical constraints dropped or weakened during migration (especially test guardrails, zero-mocking stances, cleanup lifecycle rules)\n- Hard constraints softened during compression: MUST\u002FNEVER\u002FONLY language becomes suggestions. Compare constraint strength between source and target — hard rules must survive verbatim\n- MCP servers referenced but missing from .codex\u002Fconfig.toml\n- Skill paths referenced but don't exist under .codex\u002Fskills\u002F\n- Companion reference files referenced but missing on disk\n\nHIGH — Domain accuracy (VERIFY AGAINST LIVE CODEBASE):\nClaude agent bodies drift from the codebase. Every code example, route\nconstant, helper function name, directory path, router meta pattern, and\ntest infrastructure detail in the migrated files is an implicit assertion.\nVerify these against the actual repo with read-only inspection when the runtime permits:\n- Configuration constants: grep the routes config file for the exact symbol name\n- Directory paths: inspect the actual directory (e.g., locales\u002F vs i18n\u002F, source-locale vs target-locale)\n- Helper functions: grep for the function name in the relevant module\n- Router meta patterns: read the actual router file (singular role vs roles array)\n- Test infrastructure: check actual test setup files (stub dependency vs real dependency)\n- API service names: grep for the class name to confirm it exists\nIf an example references something that doesn't exist in the live codebase,\nthat is a HIGH finding — a sub-agent copying it will produce broken code.\n\nMEDIUM — Nativeness quality:\n- Agent reads as a translation rather than a native spec (Claude jargon, hedging language about \"in Codex this would be...\")\n- Knowledge Priority doesn't reflect actual Codex tool availability\n- Sandbox recommendation mismatches agent's access pattern\n- Leftover [REVIEW:] or [TODO:] annotations\n- Sections exceed 40 lines (should extract to companion ref)\n\nOUTPUT (per finding):\n  SEVERITY: {CRITICAL|HIGH|MEDIUM}\n  FILE: {path}\n  ISSUE: {one-line}\n  FIX: {concrete instruction}\n\nIf clean: \"NO_FINDINGS\"\nEnd with: \"AUDIT_COMPLETE\"\n```\n\n### 5b. Auto-Address Findings\n\nParse audit output. For each finding:\n\n- **CRITICAL\u002FHIGH** — Fix immediately via Edit tool. Surgical edits only — do\n  NOT re-run the migration script.\n- **MEDIUM** — Fix if mechanical. Flag to user only if the fix requires judgment.\n\nDo not spawn a second auditor for fixes. The parent applies fixes, then reuses\nthe same auditor thread for convergence.\n\nFor dashboard-driven review-only entry, keep the parent-thread return compact:\n\n- verdict\n- top findings or `NO_FINDINGS`\n- next action\n- review-report path when available\n\nDo not paste the full audit transcript into the main thread unless the user\nexplicitly asks for it.\n\n### 5c. Convergence Check\n\nReuse the same live nativeness-audit sub-agent via `send_input(...)` for a\nfocused re-audit. Do not respawn the auditor unless the original agent died.\n\n```\nsend_input({\n  target: agent.id,\n  message: `CONVERGENCE CHECK: Previous audit found {N} issues, all addressed.\n\n  This is a READ-ONLY audit.\n  - Do not edit files\n  - Do not call apply_patch\n  - Do not rerun migration scripts\n  - Verify paths and symbols through read-only inspection when the runtime permits\n\n  Re-read these files and verify:\n  1. Previous findings resolved\n  2. No new CRITICAL\u002FHIGH issues introduced by fixes\n  3. Each agent still reads as a native Codex sub-agent\n\n  FILES: {paths that had findings}\n  GOLD STANDARD: {reference migrated agent artifact under .codex\u002Fagents\u002F}\n\n  Same output format. \"NO_FINDINGS\" if clean. End with \"AUDIT_COMPLETE\".`\n})\nresult = wait_agent({\"targets\": [agent.id]})\n```\n\nIf the initial audit already returned `NO_FINDINGS`, skip convergence, record\n`native` by default, and close the auditor immediately unless the user asked\nfor audit-only behavior.\n\n### 5d. Convergence Decision\n\nNative completion rule:\n\n- The agent's execution contract must be re-expressed in Codex sub-agent terms without flattening its original operational role, decision boundaries, or constraint model. If the file is format-correct but semantically flattened, do not declare it native.\n\n| Result | Action |\n|---|---|\n| `NO_FINDINGS` | Auto-record `native`, then proceed to Step 6 |\n| Only MEDIUM | Proceed to Step 6, note as \"Acknowledged minor items\" |\n| Any CRITICAL\u002FHIGH | **STOP** — escalate to user. Do not declare complete. |\n\n**Hard cap**: 2 cycles (audit + convergence). Persistent critical issues =\nsystemic problem requiring human judgment.\n\nLifecycle rule:\n\n- Always `close_agent({ target: agent.id })` before leaving Step 5, whether the\n  result is success, acknowledged-medium, or escalation.\n- Save the full nativeness review to a markdown report when the review is\n  meant to be recorded later. Reuse the existing agent-migration report\n  directories or an explicit `\u002Ftmp` review path, then attach that path through\n  `--review-evidence` at tracker close-out.\n\n## Step 6: Report\n\n### Single Agent\n\n```\nMigration Report: {name}\n  Tier: {1|2|3}\n  Source: .claude\u002Fagents\u002F{name}.md ({N} lines)\n  Target: .codex\u002Fagents\u002F{name}.toml ({M} lines)\n  Companion: .codex\u002Fagents\u002Freferences\u002F{name}-domain.md (if extracted)\n  Status: {COMPLETE|REVIEW_NEEDED|SKELETON_GENERATED|ALREADY_MIGRATED}\n  Sandbox: {read-only|workspace-write}\n  Validation: {PASS|FAIL (details)}\n  Codex Compliance: {NATIVE (0 findings)|NATIVE ({N} fixed)|ESCALATED (details)}\n  Fields mapped: {list}\n  Fields dropped: {list with reason}\n  Remaining gaps: {items needing attention}\n```\n\n### Batch Summary\n\nTable of migrated agents with tier, status, and validation result.\n\n## Migration Order\n\nWhen migrating all agents, process in this order:\n\n1. **example-agent-a** (Tier 1) — simplest, validates the pipeline\n2. **example-agent-i, example-agent-l, example-agent-j, example-agent-k** (Tier 2)\n3. **example-agent-h, example-agent-g** (Tier 2, borderline complexity)\n4. **example-agent-c, example-agent-f** (Tier 3, companion ref extraction)\n5. **example-agent-d, example-agent-e** (Tier 3, MCP gap resolution needed)\n6. **example-agent-m** (Tier 3, LAST — depends on all leaf agents being stable)\n\n## Anti-Patterns\n\n| Don't | Do Instead |\n|---|---|\n| Preserve frontmatter delimiters | Strip frontmatter, map to markdown sections |\n| Exceed 1000 lines | Extract verbose domain content to companion refs |\n| Convert hooks to comments | Map to completion gate in Runtime Configuration |\n| Map `tools` to a \"Tools\" section | Use Constraints + Recommended Sandbox sections |\n| Keep absolute `\u002FUsers\u002F...` paths | Strip to repo-relative paths |\n| Mechanical conversion on Tier 3 | Generate skeleton, hand-author domain sections |\n| Use fabricated Codex primitives | Verify against official Codex docs |\n| Skip compliance audit for \"simple\" agents | Always run — even T1 agents can have namespace drift |\n| Let the nativeness auditor edit files directly | Keep the auditor read-only by prompt contract — parent workflow applies fixes |\n| Loop audit >2 cycles | Escalate to user after convergence if CRITICAL remains |\n| Report completion before audit passes | Step 5 must gate Step 6 |\n| Treat format-correct as native-compliant | A file can pass validation but still read as a port |\n| Trust Claude agent body as accurate | Agent bodies drift — verify domain examples against live codebase (Step 2.5) |\n| Substitute or drop missing skills silently | Treat missing skills as a blocker — resolve via MIGRATE\u002FSUBSTITUTE\u002FDROP in Step 1b |\n| Copy code examples verbatim from Claude source | Every route constant, helper name, meta pattern is an assertion — grep to confirm |\n| Weaken safety constraints during compression | Preserve hard rules verbatim: \"preserve setup boundaries\", \"preserve integration constraints\", \"preserve test-scope constraints\" |\n| Use port-artifact language in companion files | \"Extracted during Codex migration\" → \"Reference for X agent. Use when Y.\" |\n\n## Migration Review Guidance\n\n**Rationale**: Migration audits often find\nformat issues and stale source knowledge\ncarried over from the Claude agent body.\n\n**Key patterns:**\n1. **Claude agent bodies are NOT authoritative** — they're cached snapshots of\n   codebase knowledge. Configuration constants get renamed, test infrastructure gets\n   replaced, helpers get deleted. Step 2.5 exists to catch this BEFORE writing.\n2. **Companion references are assertion-dense** — every code example is a claim\n   about codebase state. More specific = more fragile. When in doubt, use\n   neutral descriptions (\"use the module's existing pattern\") over stale specifics.\n3. **The initial audit catches ecosystem issues; convergence catches domain\n   drift** — this asymmetry is by design now. The initial audit prompt includes\n   \"Domain accuracy: VERIFY AGAINST LIVE CODEBASE\" to push more domain checks\n   into the first cycle, reducing convergence-cycle findings and token cost.\n4. **Unmigrated skill references are invisible until audit** — `ls .codex\u002Fskills\u002F`\n   takes 1 second but saves an entire audit finding + fix cycle.\n5. **Specific constraints need review** — \"real dependencies over simplified fixtures\" is\n   not the same rigor as \"specific external dependency requirements — no lightweight stand-ins, no\n   simplified fixtures.\" Keep the actionable requirement clear.\n\n## Shared References\n\nThese references are symlinked from the sibling `migrate-to-codex` skill:\n\n- [primitive-mapping.md](references\u002Fprimitive-mapping.md) — Claude→Codex tool mapping\n- [architectural-patterns.md](references\u002Farchitectural-patterns.md) — 6 migration patterns\n\nAgent-specific references:\n\n- [agent-complexity-classifier.md](references\u002Fagent-complexity-classifier.md) — Tier decision tree\n- [agent-field-mapping.md](references\u002Fagent-field-mapping.md) — Frontmatter→section mapping\n- [codex-agent-template.md](references\u002Fcodex-agent-template.md) — Gold standard template\n- [legacy-subagent-roi.md](references\u002Flegacy-subagent-roi.md) — Which legacy\n  sub-agent features are worth using in this migration workflow\n",{"name":5,"description":7},"main","51b96c318377cb9b51e767cfb6b593637b46c654",".codex\u002Fskills\u002Fmigrate-agents-to-codex",5,"https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex","https:\u002F\u002Fgithub.com\u002Fzuharz","2026-08-20 18:04:37",{"source":8,"skillName":5,"commands":57,"prompt":67,"zipAvailable":68},[58,61,64],{"tool":59,"command":60},"npx","npx skills add zuharz\u002Fccode-to-codex --skill migrate-agents-to-codex",{"tool":62,"command":63},"bunx","bunx skills add zuharz\u002Fccode-to-codex --skill migrate-agents-to-codex",{"tool":65,"command":66},"pnpm","pnpm dlx skills add zuharz\u002Fccode-to-codex --skill migrate-agents-to-codex","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fmigrate-agents-to-codex\u002FSKILL.md",true,[70,76,80,84,88,92,96,100,104,110,114],{"path":71,"resourceType":72,"resourceTypeDesc":73,"sizeBytes":74,"sourceHtmlUrl":75},"references\u002Fagent-complexity-classifier.md","REFERENCE","参考文档",2851,"https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Freferences\u002Fagent-complexity-classifier.md",{"path":77,"resourceType":72,"resourceTypeDesc":73,"sizeBytes":78,"sourceHtmlUrl":79},"references\u002Fagent-field-mapping.md",14288,"https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Freferences\u002Fagent-field-mapping.md",{"path":81,"resourceType":72,"resourceTypeDesc":73,"sizeBytes":82,"sourceHtmlUrl":83},"references\u002Farchitectural-patterns.md",3173,"https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Freferences\u002Farchitectural-patterns.md",{"path":85,"resourceType":72,"resourceTypeDesc":73,"sizeBytes":86,"sourceHtmlUrl":87},"references\u002Fcodebase-verification-prompt.md",2011,"https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Freferences\u002Fcodebase-verification-prompt.md",{"path":89,"resourceType":72,"resourceTypeDesc":73,"sizeBytes":90,"sourceHtmlUrl":91},"references\u002Fcodex-agent-template.md",6196,"https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Freferences\u002Fcodex-agent-template.md",{"path":93,"resourceType":72,"resourceTypeDesc":73,"sizeBytes":94,"sourceHtmlUrl":95},"references\u002Flegacy-subagent-roi.md",5563,"https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Freferences\u002Flegacy-subagent-roi.md",{"path":97,"resourceType":72,"resourceTypeDesc":73,"sizeBytes":98,"sourceHtmlUrl":99},"references\u002Fprimitive-mapping.md",7371,"https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Freferences\u002Fprimitive-mapping.md",{"path":101,"resourceType":72,"resourceTypeDesc":73,"sizeBytes":102,"sourceHtmlUrl":103},"references\u002Fsubagent-migration-guide.md",12298,"https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Freferences\u002Fsubagent-migration-guide.md",{"path":105,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":108,"sourceHtmlUrl":109},"scripts\u002Fmigrate_claude_agents_to_codex.py","SCRIPT","脚本",56426,"https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Fmigrate_claude_agents_to_codex.py",{"path":111,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":112,"sourceHtmlUrl":113},"scripts\u002Frun_agent_migration_workflow.py",20209,"https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Fscripts\u002Frun_agent_migration_workflow.py",{"path":115,"resourceType":106,"resourceTypeDesc":107,"sizeBytes":116,"sourceHtmlUrl":117},"tests\u002Ftest_migrate_claude_agents_to_codex.py",20973,"https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fmigrate-agents-to-codex\u002Ftests\u002Ftest_migrate_claude_agents_to_codex.py",[119,143,160,186,208,221],{"skillNo":120,"name":121,"nameZh":6,"description":122,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":123,"categories":124,"keywords":126,"publishedAt":44},"01M70F7Q7VKHHX3P56E5FAMWT1","hello-world-skill","Create or update hello-world.txt with a Codex greeting. Use when you need a minimal instruction-only Agent Skill example with explicit verification.","https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002Fexamples\u002Fhello-world-skill\u002FSKILL.md",[125],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[127,128,129,130,131,28,132,133,134,135,25,136,137,138,139,140,141,142],"hello world skill","hello world","hello","world","you","hello-world","with","minimal","agent skill","create","greeting","update","verification","use","example","only",{"skillNo":144,"name":145,"nameZh":6,"description":146,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":147,"categories":148,"keywords":150,"publishedAt":44},"01M70F7EKPMNMBV3NHQEK3AJVV","verify-skill-migration","Validator-backed migration QA for Codex skills and related docs","https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fverify-skill-migration\u002FSKILL.md",[149],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[151,152,153,154,25,155,156,157,158,159],"verify","migration","verify skill","verify skill migration","docs","validator","qa","for","codex skills",{"skillNo":161,"name":162,"nameZh":6,"description":163,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":164,"categories":165,"keywords":174,"publishedAt":44},"01M70F74MM48XA1FNC6GX4373Z","migration-dashboard","Codex-native migration analysis dashboard for Claude→Codex skills and agents. Reads `migration-state.json` to report progress, drift, velocity, nativeness-review state, validator results, and next-batch recommendations. Use for \"migration status\", \"what should I migrate next\", \"migration progress\", or \"migration dashboard\".","https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fmigration-dashboard\u002FSKILL.md",[166,169],{"categoryNo":167,"categoryName":168,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000013","分析与可视化",{"categoryNo":170,"categoryName":171,"taxonomyType":172,"taxonomyTypeDesc":173},"01JBSEEDCAT000000000000033","数据分析师","PROFESSION","适用职业",[152,175,176,159,158,156,33,177,178,179,180,181,140,182,26,183,184,25,43,185],"dashboard","migration dashboard","progress","recommendations","velocity","next","batch","results","analysis","state","drift",{"skillNo":187,"name":188,"nameZh":6,"description":189,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":190,"categories":191,"keywords":193,"publishedAt":44},"01M70F6T65KA26WPCXS7B50H5X","migrate-to-codex","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.","https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fmigrate-to-codex\u002FSKILL.md",[192],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[26,194,25,195,196,181,197,43,198,33,199,200,34,201,202,203,204,205,206,207],"migrate to codex","command","audit","workflow","hooks","result","mode","as","classify","commands","project","local","codex skill","compatibility",{"skillNo":209,"name":210,"nameZh":6,"description":211,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":212,"categories":213,"keywords":215,"publishedAt":44},"01M70F6A9CKGYM43NZKSDZMZAA","example-skill","Minimal placeholder skill for public migration examples.","https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fexample-skill\u002FSKILL.md",[214],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[141,216,217,218,158,134,152,219,220],"example skill","public","placeholder skill","examples","placeholder",{"skillNo":222,"name":223,"nameZh":6,"description":224,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":225,"categories":226,"keywords":227,"publishedAt":44},"01M70F685NJA8WV5PCXRHF4DX9","example-commit-helper","Minimal placeholder commit helper for public migration examples.","https:\u002F\u002Fgithub.com\u002Fzuharz\u002Fccode-to-codex\u002Fblob\u002Fmain\u002F.codex\u002Fskills\u002Fexample-commit-helper\u002FSKILL.md",[],[228,141,229,230,231,158,134,152,217,219,220],"commit","helper","commit helper","example commit helper"]