🟡 Converting your project

Instead of copying/renaming/converting by hand, open the DESTINATION agent (Codex if you're coming from Claude, and vice versa) and ask it to read the current config and create the equivalent.

Manual migration takes hours and has subtle bugs. An agent does it in minutes, with a chance of catching nuances (TOML syntax, sidecar) you might miss.

The “agents migrate agents” principle, documentation research as part of the prompt, and subsequent validation by a human.

An explicit prompt that tells the agent: read CLAUDE.md and generate an equivalent AGENTS.md; read .claude/agents/ and generate .codex/agents/ in TOML; read .claude/skills/ and copy/adapt them to .agents/skills/; research the documentation for both to make sure.

Vague prompts get vague results. The standardized template ensures complete coverage: AGENTS.md + .codex/ + .agents/ + adapting agents to TOML.

Prompt order matters, explicitly ask for documentation research, list expected files, and request a report on what changed.

List of what to ALWAYS check after the agent says "migrated": AGENTS.md has equivalent instructions; agents in TOML load without errors; skills appear in the listing command; MCP servers connect; permissions make sense.

An agent can say “done” and have skipped something. The checklist is your insurance policy. Five minutes of validation saves hours of “why isn't this working?”

Feature-based validation (not just by file), smoke test (invoke a simple skill), check openai.yaml in skills with MCP deps.

(1) Skill in .codex/skills instead of .agents/skills; (2) backtick-bang copied without a fallback; (3) long description truncated; (4) agents in markdown instead of TOML; (5) expecting auto-dispatch in Codex.

These are the 5 errors that show up in almost every migration. Once you know them, you can spot them at a glance. Without that knowledge, you spend hours debugging "why it doesn't trigger".

Correct folder path, injection conversion, description limit, TOML format, explicit invocation.

After the initial migration, every major change to CLAUDE.md needs to become a change in AGENTS.md (and vice versa). Same for skills. That’s the “tax” of maintaining both runtimes.

Without discipline, the two drift apart within weeks, and you end up with two different projects. Manual discipline works; polyskill (T5) automates it for skills.

Rule: “change it here, change it there,” hook or pre-commit checklist, divergence detection, polyskill as a solution for skills (not for CLAUDE.md/AGENTS.md).

You can use Claude Code as your main agent and Codex just to run specific skills (or vice versa). It’s not all or nothing. Share the source code and keep only the skills duplicated.

Reduces duplication costs. Many people migrate everything thinking they need to, when it would be enough to port 2-3 critical skills to Codex.

Primary vs. auxiliary agents, minimal duplication scope, “polyglot skill” ported with polyskill (T5).

After the initial migration and the experience of maintaining both, comes the “okay, I don’t want to do this manually anymore.” That’s where Trail 5 comes in: polyskill. One source, two outputs, drift policy.

To understand the pain before seeing the solution. Anyone who understands the pain of maintaining two divergent skills will appreciate polyskill much more.

Canonical source of truth, adapters per runtime, automated build, drift hash, Claude ↔ Codex round-trip.