Claude To Codex

---
name: claude-to-codex
description: Scans global/claude/skills/ and global/claude/agents/ for items missing from global/codex/skills/ and global/codex/agents/, presents the gap list for approval, then adapts each approved item to Codex format and writes it to the global/codex/ directory, then runs ./install.sh --codex. Project-local skill - only meaningful inside the AI-Tools repo. Trigger when the user says "sync from claude", "port claude skill to codex", "adapt claude to codex", "what claude skills are missing from codex", or "port this 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:

```bash
# 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:

```text
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:

```toml
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:

```bash
./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.