| 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:
comm -23 \
<(ls .claude/skills/ 2>/dev/null | sort) \
<(ls .agents/skills/ 2>/dev/null | sort)
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:
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 conventiondescription: -> 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:
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.
