Port Project Claude

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

# Port project-local Codex artifacts to Claude Code

Finds project-local Codex skills/agents (`.agents/skills/`, `.codex/agents/`) that have
no Claude Code counterpart in `.claude/skills/` or `.claude/agents/`, and adapts them to
Claude Code conventions with per-item approval before any write.

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

## Procedure

### 1. Compute the gap

Run both diffs in parallel:

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

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

Note: use two separate `ls` calls (not `ls dir1 dir2`) — the two-argument form of `ls`
prefixes output with directory headers when both dirs exist, corrupting the name list.

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

### 2. Present the gap list

Show the user two sections:

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

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

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

### 3. Adapt skills (for each approved skill)

Read `.agents/skills/<name>/SKILL.md`, then apply these substitutions:

| Find | Replace |
|---|---|
| `AGENTS.md` / `AGENTS.override.md` | `CLAUDE.md` |
| `$<skill-name>` invocation syntax | `/<skill-name>` |
| `where-agents-md` cross-references | `where-claude` |
| `audit-agent-docs` cross-references | `audit-claude-md` |
| Personal Codex config paths (`~/.codex/`, `$CODEX_HOME`) | Personal Claude config paths (`~/.claude/`) |
| Project Codex skill paths (`.agents/skills/`) | Project Claude skill paths (`.claude/skills/`) |
| Project Codex agent paths (`.codex/agents/`) | Project Claude agent paths (`.claude/agents/`) |
| "Codex" when referring to the product | "Claude Code" |
| "AGENTS" as a generic concept for instruction files | "CLAUDE.md" |

Show the adapted content to the user and require approval before writing.

Create `.claude/skills/<name>/` directory if needed, then write `.claude/skills/<name>/SKILL.md`.

### 4. Adapt agents (for each approved agent)

Locate the source TOML at `.codex/agents/<name>.toml`.

Read it and extract:
- `name` — convert underscores to hyphens (kebab-case)
- `description` — use as-is
- `developer_instructions` — becomes the Markdown body (apply the same Codex→Claude
  product reference fixes from step 3)
- `sandbox_mode = "read-only"` → explicit `tools` list (Read, Glob, Grep; add
  WebSearch/WebFetch only if the instructions reference web access)
- `model_reasoning_effort = "medium"` → `model: haiku`; `"high"` → omit (defaults to Sonnet)

Write `.claude/agents/<name>.md` in this shape:

```markdown
---
name: <kebab-name>
description: <description from TOML>
tools:
  - Read
  - Glob
  - Grep
---

<developer_instructions content, with Codex→Claude product references fixed>
```

Flag the output explicitly as a lossy TOML→Markdown conversion and require human review
before writing.

### 5. Wrap up

Report:
- Items ported with their destination paths
- Items skipped and the reason (already exists, user declined, conversion flagged)
- Remind the user to restart Claude Code for new `/commands` to appear in autocomplete

## Guardrails

- Never overwrite an existing file in `.claude/` — skip with a per-item warning if the target already exists.
- Never modify any file under `.agents/` or `.codex/` — they are read-only sources.
- Never write to global `~/.claude/` paths — only to the project-local `.claude/` directory.
- Always show the adapted content and get per-item approval before writing.
- TOML→Markdown agent conversion is lossy: flag it explicitly; do not claim it is complete.
- Cross-references that differ between products (`where-agents-md` vs `where-claude`,
  `audit-agent-docs` vs `audit-claude-md`) must be noted — do not rename silently.
- Create target directories (`.claude/skills/<name>/`, `.claude/agents/`) as needed.