codex-to-cc

Convert Codex Plugin → Claude Code

Convert a single plugin from Codex format to Claude Code-compatible format.

When to activate

• User says "convert X from Codex to CC", "add Claude Code support for X", "reverse-port X"
• User provides a Codex plugin path and asks for CC compatibility
• Round-trip recovery: CC plugin was converted to Codex, now needs CC files restored

Inputs

• Plugin path — relative to repo root, e.g. plugins/my-codex-plugin
• Repo root — directory containing .agents/plugins/marketplace.json (default: detect from cwd)

Workflow

Phase 0: Vendor external plugins

When the plugin lives outside this repository, copy it into plugins_dir before conversion. Review license and attribution, resolve name collisions, discard stale foreign generated artifacts after review, and explicitly choose the source of truth when attaching. Deterministic scripts never copy files between repositories.

Step 1 — Read source

Read the following files from the target plugin (skip if absent):

1. <plugin-path>/.codex-plugin/plugin.json — required
2. <plugin-path>/skills/ directory listing — list all SKILL.md files
3. <plugin-path>/.mcp.json — optional
4. <plugin-path>/README.md — optional
5. <plugin-path>/.plugin-cross-port.json — optional (check source_of_truth)

If .codex-plugin/plugin.json is missing, stop and report: "Not a Codex plugin: no .codex-plugin/plugin.json found."

If .plugin-cross-port.json exists with source_of_truth: claude-code, warn:

"This plugin was originally created in Claude Code. Reverse conversion may produce redundant files. Proceed?"

Step 2 — Check for existing CC manifest

If <plugin-path>/.claude-plugin/plugin.json already exists, read it. Ask:

".claude-plugin/plugin.json already exists. Overwrite or merge?"

Step 3 — Generate .claude-plugin/plugin.json

Build the CC manifest from the Codex manifest:

{
  "name": "<same as Codex name>",
  "description": "<same description>",
  "version": "<same version>",
  "author": {
    "name": "<author.name>",
    "email": "",
    "url": ""
  },
  "keywords": ["<interface.category>", "codex", "cross-platform"],
  "license": "MIT",
  "skills": [
    "./skills/<name>/SKILL.md"
    // list all SKILL.md files from skills/
  ]
}