Port Project Codex

---
name: port-project-codex
description: Scans the current project's .claude/skills/ and .claude/agents/ directories for items missing from the project's .agents/skills/ and .codex/agents/ directories, presents the gap list for approval, adapts each approved item to Codex format, and writes to project-local Codex paths. Never writes to global ~/.codex/ or modifies .claude/. Global and project-agnostic. Trigger when the user says "port project codex", "port-project-codex", "replicate project claude skills for codex", "sync project .claude to .agents", "sync project .claude to .codex", "bring claude skills into codex", "copy project claude", or "port project skills to codex".
---

# Port project-local Claude Code artifacts to Codex

Finds project-local Claude Code skills and agents that have no Codex counterpart, adapts
approved items to Codex conventions, and writes only to the current project's
project-local Codex directories.

Source: `.claude/skills/` and `.claude/agents/` inside the current working directory.
Target: `.agents/skills/` and `.codex/agents/` inside the current working directory.
Never touches global `~/.codex/` or modifies any `.claude/` file.

## Procedure

### 1. Compute the gap

Run both diffs:

```bash
# Skills missing from .agents/
comm -23 \
  <(ls .claude/skills/ 2>/dev/null | sort) \
  <(ls .agents/skills/ 2>/dev/null | sort)

# Agents missing from .codex/ (strip .md extension)
comm -23 \
  <(ls .claude/agents/ 2>/dev/null | sed 's/\.md$//' | sort) \
  <(ls .codex/agents/ 2>/dev/null | sed 's/\.toml$//' | sort)
```

If both lists are empty, report
"No gaps found - project .claude/, .agents/, and .codex/ are in sync." and stop.

### 2. Present the gap list

Show the user two sections:

```text
Skills to port   (.claude/skills/<name>/SKILL.md -> .agents/skills/<name>/SKILL.md)
  - <name>
  ...

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

Ask which items to port. Require explicit per-item approval before any write.

### 3. Adapt skills

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

| Find | Replace |
|---|---|
| `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` |
| Personal Claude config paths (`~/.claude/`) | Personal Codex config paths (`${CODEX_HOME:-~/.codex}/`) |
| Project Claude skill paths (`.claude/skills/`) | Project Codex skill paths (`.agents/skills/`) |
| Project Claude agent paths (`.claude/agents/`) | Project Codex agent paths (`.codex/agents/`) |
| "Claude Code" when referring to the product | "Codex" |
| "CLAUDE.md" as a generic concept for instruction files | "AGENTS.md" |

Note cross-references that differ between products, especially `where-claude` vs
`where-agents-md` and `audit-claude-md` vs `audit-agent-docs`; do not silently rename
them without calling out the change.

Show the adapted content to the user and require approval before writing to
`.agents/skills/<name>/SKILL.md`. Create `.agents/skills/<name>/` as needed only after
approval and only if the target file does not already exist.

### 4. Adapt agents

For each approved agent, read `.claude/agents/<name>.md`. This is a lossy
Markdown-to-TOML conversion. Flag that explicitly and require human review before
writing.

Extract from frontmatter and body:

- `name:` -> TOML `name`, converting hyphens to underscores for TOML convention
- `description:` -> TOML `description`
- Markdown body -> TOML `developer_instructions`
- `tools:` list with only `Read`, `Glob`, and `Grep` -> `sandbox_mode = "read-only"`
- `model: haiku` -> `model_reasoning_effort = "medium"`
- absent `model` -> omit model settings and use the Codex default

Apply the same Claude-to-Codex product reference fixes from step 3 to
`developer_instructions`.

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

```toml
name = "<underscore_name>"
description = "<description from frontmatter>"
developer_instructions = """
<body content, with Claude→Codex product references fixed>
"""
sandbox_mode = "read-only"
```

If the Claude agent declares tools beyond `Read`, `Glob`, and `Grep`, stop for that item
and ask the user how to represent the permissions in Codex. Do not guess a broader
sandbox mode.

### 5. Wrap up

Report:

- Items ported, with destination paths
- Items skipped and why: already exists, user declined, or conversion flagged
- A reminder to restart Codex for new `$commands` to appear

## Guardrails

- Never overwrite an existing file in `.agents/skills/` or `.codex/agents/`; skip with a per-item warning.
- Never modify any file under `.claude/`; it is a read-only source.
- Never write to global `~/.codex/`; write only to project-local `.agents/skills/` and `.codex/agents/`.
- Always show adapted content and get per-item approval before writing.
- Markdown-to-TOML agent conversion is lossy: flag it explicitly.
- Cross-references that differ between products must be noted, not silently renamed.
- Create target directories only after the user approves the specific item to port.