Port project 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:

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

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:

---
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.