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

> Discover how plugin-to-Codex conversion generates prompts and skills for compound engineering. Learn about the claude-to-codex.ts converter and its artifacts.

- Repository: [Every/compound-engineering-plugin](https://github.com/everyinc/compound-engineering-plugin)
- Tags: internals
- Published: 2026-02-16

---

**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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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.

```typescript
// 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.

```typescript
// 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.

```typescript
// 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`.

```typescript
// 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.

```typescript
// 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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`

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

```

### Step 7: Writing the Codex Bundle

`writeCodexBundle` in [`src/targets/codex.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/SKILL.md) files for converted commands and agents.

```typescript
// 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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`.

```typescript
// 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:

```bash

# 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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/commands/convert.ts) orchestrates the entire process, writing the final bundle to the target directory via [`src/targets/codex.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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.