How Plugin-to-Codex Conversion Handles Prompt and Skill Generation in Compound Engineering

The plugin-to-Codex conversion generates three distinct artifacts—prompt files, imported skill directories, and generated skill files—by transforming Claude Code plugin commands and agents into Codex-compatible formats using the claude-to-codex.ts converter.

The EveryInc/compound-engineering-plugin repository provides a CLI tool that automates the migration from Claude Code plugins to OpenAI Codex. The plugin-to-Codex conversion process creates a structured .codex directory containing prompts that reference generated skills, ensuring seamless translation of plugin functionality while preserving the original logic.

The Three Artifacts Generated by Plugin-to-Codex Conversion

The conversion process in src/converters/claude-to-codex.ts produces a CodexBundle containing three distinct artifact types that work together to replicate plugin behavior in Codex.

Prompt Files (.codex/prompts/*.md)

For every invocable command (those without disableModelInvocation), the converter generates a unique prompt name using uniqueName() and creates a markdown file with YAML front-matter. The renderPrompt function builds the prompt body to include instructions pointing to the corresponding generated skill.

Imported Skill Directories

All original skill directories from the Claude plugin are copied unchanged via the skillDirs array. These maintain their original structure under .codex/skills/<skill-name>/ without transformation.

Generated Skill Files (.codex/skills/<name>/SKILL.md)

Two categories of generated skills are created:

1. Command-derived skills (convertCommandSkill) – Convert invocable commands into standalone skills
2. Agent-derived skills (convertAgent) – Convert Claude agents into Codex-compatible skills

Both types use formatFrontmatter from src/utils/frontmatter.ts to prepend YAML metadata (name, description, arguments, allowed tools) and transform body content with transformContentForCodex.

Core Conversion Pipeline in claude-to-codex.ts

The convertClaudeToCodex function orchestrates a seven-step pipeline to transform plugin components.

Step 1: Collecting Plugin Data

The converter receives a parsed ClaudePlugin and extracts skill directories, agents, and commands.

// src/converters/claude-to-codex.ts#L10-L20
const skillDirs = plugin.skills.map(s => ({ name: s.name, sourceDir: s.sourceDir }));
const invocableCommands = plugin.commands.filter(c => !c.disableModelInvocation);

Step 2: Generating Unique Names

The normalizeName function creates URL-friendly slugs, while uniqueName guarantees no collisions among prompts, command-skills, and agent-skills.

// src/converters/claude-to-codex.ts#L24-L27
const promptName = uniqueName(normalizeName(command.name), promptNames);
const commandSkill = convertCommandSkill(command, usedSkillNames);

Step 3: Rendering Prompts

The renderPrompt function builds front-matter containing description and argument-hint, then constructs a body that instructs Codex to invoke the generated skill.

// src/converters/claude-to-codex.ts#L43-L53
const instructions = `Use the $${skillName} skill for this command …`;
const body = [instructions, "", transformedBody].join("\n").trim();
return formatFrontmatter(frontmatter, body);

Step 4: Converting Commands to Skills

convertCommandSkill adds sections for arguments and allowed tools, then transforms the original command body using transformTaskCalls.

// src/converters/claude-to-codex.ts#L62-L82
const transformedBody = transformTaskCalls(command.body.trim());
const content = formatFrontmatter(frontmatter, body.length ? body : command.body);

Step 5: Converting Agents to Skills

convertAgent creates a skill whose body may include a "Capabilities" section, then applies the same content transformation pipeline.

// src/converters/claude-to-codex.ts#L42-L60
let body = transformContentForCodex(agent.body.trim());

Step 6: Transforming Content Syntax

The transformContentForCodex function in src/converters/claude-to-codex.ts handles three critical syntax rewrites:

• Task <agent>(args) → Use the $<skill> skill to: args
• /command → /prompts:<normalized>
• @agent-name → $<skill> skill

// src/converters/claude-to-codex.ts#L85-L138

Step 7: Writing the Codex Bundle

writeCodexBundle in src/targets/codex.ts creates the .codex directory structure, writing prompts to prompts/<name>.md, copying original skills to skills/<skill-name>/, and generating SKILL.md files for converted commands and agents.

// src/targets/codex.ts#L6-L30, L24-L30

Syntax Transformations for Codex Compatibility

The plugin-to-Codex conversion handles three specific syntax differences between Claude Code and Codex:

Task invocation rewriting – Claude's Task <agent>(args) syntax becomes Codex's skill invocation pattern: Use the $<skill> skill to: args.

Slash command normalization – Claude slash commands like /command are rewritten to Codex prompt references: /prompts:<normalized>.

Agent reference conversion – Claude @agent-name mentions become $<skill> skill references in the Codex output.

These transformations ensure that plugin logic remains functional while conforming to Codex's skill-based architecture.

CLI Integration and Usage

The convert command in src/commands/convert.ts orchestrates the entire plugin-to-Codex conversion pipeline. It selects the codex target, invokes the convertClaudeToCodex converter, and passes the resulting CodexBundle to writeCodexBundle.

// src/commands/convert.ts#L90-L96
const bundle = target.convert(plugin, options);
await target.write(primaryOutputRoot, bundle);

To execute the conversion from the command line:

# Convert a Claude plugin to Codex, writing into ~/.codex

bun run src/commands/convert.ts /path/to/plugin --to codex --codex-home ~/.codex

This generates the complete .codex directory structure with prompts referencing generated skills, ready for use with OpenAI Codex.

Summary

• The plugin-to-Codex conversion generates three artifacts: prompt files (.codex/prompts/*.md), imported original skill directories, and generated skill files (.codex/skills/<name>/SKILL.md).
• The conversion pipeline in src/converters/claude-to-codex.ts handles name normalization, front-matter generation, and content transformation through seven distinct steps.
• Syntax transformations convert Claude-specific patterns (Task, /command, @agent) into Codex-compatible skill invocations and prompt references.
• The convert command in src/commands/convert.ts orchestrates the entire process, writing the final bundle to the target directory via src/targets/codex.ts.

Frequently Asked Questions

How does the plugin-to-Codex conversion handle naming collisions between commands and agents?

The conversion uses the uniqueName function in src/converters/claude-to-codex.ts to guarantee no collisions among prompt names, command-derived skills, and agent-derived skills. It maintains a usedSkillNames set and appends numeric suffixes when necessary to ensure every generated artifact has a distinct identifier.

What happens to Claude Code slash commands during the conversion?

The transformContentForCodex function rewrites Claude slash commands (/command) into Codex prompt references (/prompts:<normalized>). This transformation occurs during Step 6 of the conversion pipeline, ensuring that command invocations in the original plugin body correctly reference the generated prompt files in the Codex environment.

Are original skill directories modified during the plugin-to-Codex conversion?

No, original skill directories are copied unchanged. The writeCodexBundle function in src/targets/codex.ts copies these directories directly under .codex/skills/<skill-name>/ without transformation. Only commands and agents are converted into new generated skill files, while pre-existing skills maintain their original structure and content.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}