Claude to codex

Port Claude Artifacts To Codex

Finds Claude Code skills/agents that have no Codex counterpart in this repo and adapts them to Codex conventions, one item at a time with per-item approval.

Procedure

1. Compute The Gap

Run both diffs in parallel:

# Skills missing from codex/
comm -23 \
  <(ls global/claude/skills/ | sort) \
  <(ls global/codex/skills/ | sort)

# Agents missing from codex/ (strip extensions for comparison)
comm -23 \
  <(ls global/claude/agents/ | sed 's/\.md$//' | sort) \
  <(ls global/codex/agents/ | sed 's/\.toml$//' | sort)

Treat these product-specific name pairs as already equivalent unless the user explicitly wants a duplicate:

Claude Code	Codex
audit-claude-md	audit-agent-docs
where-claude	where-agents-md

If both lists are empty after applying the equivalence map, report "No gaps found - global/claude/ and global/codex/ are in sync" and stop.

2. Present The Gap List

Show the user two sections:

Skills to port   (global/claude/skills/<name>/SKILL.md -> global/codex/skills/<name>/SKILL.md)
  - <name>
  ...

Agents to port   (global/claude/agents/<name>.md -> global/codex/agents/<name>.toml)
  - <name>
  ...

Ask which items to port. Do not proceed without explicit approval per item.

3. Adapt Skills

For each approved skill, read global/claude/skills/<name>/SKILL.md, then apply these substitutions:

Find	Replace with
CLAUDE.md	AGENTS.md
/\<skill-name> invocation syntax	$<skill-name>
where-claude cross-references	where-agents-md
audit-claude-md cross-references	audit-agent-docs
Claude config paths (~/.claude/)	Codex config paths (~/.codex/, $CODEX_HOME when appropriate)
"Claude Code" when referring to the product/tool	"Codex"
"Claude" when used as the product/tool name	"Codex"

Show the adapted content to the user and ask for approval before writing.

Write to global/codex/skills/<name>/SKILL.md only after approval.

4. Adapt Agents

For each approved agent, read global/claude/agents/<name>.md.

Extract:

• name from YAML frontmatter;
• description from YAML frontmatter;
• tools from YAML frontmatter;
• the Markdown body as the Codex developer_instructions.

Write global/codex/agents/<name>.toml in this shape:

name = "<kebab-name>"
description = "<description from YAML>"
sandbox_mode = "read-only"
model_reasoning_effort = "medium"
developer_instructions = """
<Markdown body, with Claude->Codex product references fixed>
"""

Use sandbox_mode = "read-only" when the Claude tools are only read/search tools (Read, Glob, Grep). If the Claude agent has broader tools, flag the conversion for manual review and ask before choosing a Codex sandbox mode. TOML conversion is lossy: quote and escape strings carefully, and do not claim the result is complete until a human has reviewed it.

5. Run install.sh

After all approved writes:

./install.sh --codex

Report which symlinks were created or already correct.

6. Wrap Up

Tell the user:

• which items were ported, with destination paths;
• which items were skipped and why;
• which product-specific equivalents were intentionally not duplicated;
• that new Codex skills and agents are picked up in a new Codex session.

Guardrails

• Never overwrite an existing file in global/codex/ - skip with a warning if the target already exists.
• Never modify any file under claude/ - it is read-only source for this skill.
• Always show adapted content and get per-item approval before writing.
• Markdown agent -> TOML is inherently lossy; flag it explicitly and preserve the role's intent.
• Names that differ between products (where-claude vs where-agents-md, audit-claude-md vs audit-agent-docs) must be noted, not silently duplicated.
• Do not run ./install.sh --codex until at least one file has been written.