Claude to Codex Plugins

How to take a Claude-first plugin and make Codex first-class alongside it without forking the real workflow.

Last updated April 28, 2026

Architecture Workflow

Case study: this guide uses llm-wiki as the public example. The same pattern works for other Claude-first plugins: keep one source of truth, then add Codex as a thin packaging and verification layer. See the project guide at llm-wiki and the source at nvk/llm-wiki.

1. What “first-class Codex” actually means

It does not mean copying a Claude plugin directory, renaming some files, and hoping the behavior survives. It means Codex gets a path that feels native enough to use every day, while the real workflow stays shared.

A good end state looks like this:

Claude and Codex both expose the same important workflow.
The workflow logic exists once.
The Claude manifest and Codex manifest are thin adapters.
Codex users get a real install path, enable path, and smoke-test path.
You can improve the workflow once without hand-porting the behavior to two clients.

Bad porting pattern: “Claude plugin over here, Codex plugin over there, two separate trees, two separate docs, two separate bugs.” That is just lock-in with extra maintenance.

2. Split durable behavior from packaging

The main question is not “how do I make Codex understand Claude files?” The main question is “which parts of this plugin are the durable workflow, and which parts are just vendor glue?”

Layer	Keep shared?	Notes
Workflow instructions and protocols	Yes	The most valuable part. Keep it as the source of truth.
Helper scripts and reference docs	Yes	Do not duplicate operational logic per vendor.
Passive instruction files	Yes	Use `AGENTS.md`-style files for broad rules that should survive client churn.
Claude plugin manifest and routing	No	Keep it thin. It is packaging.
Codex plugin manifest and marketplace metadata	No	Also packaging. Keep it thin.

shared protocol / skills / docs → thin Claude wrapper + thin Codex wrapper → same helper scripts and tools underneath

3. Keep one shared workflow source

If the workflow is currently trapped inside Claude-only commands, hooks, or skills, extract the durable parts first. The easiest portable shapes are:

markdown protocol docs
shared skill content
small helper scripts
reference docs that both clients can point at

plugin-root/
  AGENTS.md
  skills/
    my-workflow/
      SKILL.md
      references/
  scripts/
    bootstrap-codex-plugin.sh
    verify-codex-plugin.sh
  .claude-plugin/
    plugin.json
  .codex-plugin/
    plugin.json

This is the real portability move: Codex support is easiest when the workflow already exists outside the Claude manifest.

4. Add Codex packaging, not a second brain

Once the behavior is shared, Codex support becomes a packaging problem. That means:

add a real .codex-plugin/plugin.json
bundle or generate Codex-visible skills from the same source
keep Codex-specific enablement and metadata in repo-local files
do not fork the workflow into a separate Codex-only logic tree

Good mental model: Claude and Codex should be two front doors into the same workshop, not two separate buildings.

In practice, “Codex first-class” usually means a few very specific things:

Codex can install or enable the plugin locally.
Codex can discover the shared skills naturally.
There is a documented verification path.
The repo can sync or regenerate Codex packaging from the shared source when needed.

5. Use a repo-local marketplace

The cleanest Codex path we have found is project-local enablement, not trying to treat every experiment as a global install from day one.

That means keeping marketplace metadata in the repo so the plugin can be tested, upgraded, and verified close to the source tree.

.agents/
  plugins/
    marketplace.json
.codex-plugin/
  plugin.json
scripts/
  bootstrap-codex-plugin.sh
  verify-codex-plugin.sh

This keeps the Codex side predictable:

the enable path is documented
the plugin version and source are obvious
local changes can be exercised before publishing anything more global

6. Bootstrap and verify the Codex path

Do not stop at “the files exist.” A first-class Codex path needs a real bootstrap and verification flow.

The pattern that held up best in practice is:

bootstrap the local marketplace or plugin registration
enable the plugin in project-local Codex config
run a runtime smoke test against the actual Codex prompt input path
document the operator-facing commands

scripts/bootstrap-codex-plugin.sh
scripts/verify-codex-plugin.sh
tests/test-codex-runtime.sh

That verification layer matters more than people think. It catches the difference between “the manifest parses” and “Codex actually sees the right behavior.”

7. Case study: llm-wiki

llm-wiki is a good example because the useful part was never just the Claude manifest. The durable value lived in the wiki protocol, the shared skill content, the reference docs, and the helper logic. That made Codex support a packaging and verification problem instead of a full rewrite.

The path that worked looked like this:

keep the wiki protocol and research workflow shared
keep Claude packaging as one adapter
add Codex packaging as another adapter
use a repo-local marketplace for Codex-first-class local enablement
add bootstrap and verify scripts instead of relying on hand-wavy install instructions
use a real Codex runtime smoke test, not just manifest inspection

Key lesson from llm-wiki: the big win was not “port to Codex.” The big win was “stop treating Claude packaging as the only place the workflow exists.”

If you want the functional outcome, read the public llm-wiki guide. If you want the general migration pattern, this page is the abstraction of that move.

8. Common mistakes

Copying the Claude tree wholesale and then drifting forever.
Leaving the real workflow inside one manifest so the other client only gets a weak mirror.
Skipping runtime verification and trusting that parsed files mean working behavior.
Making Codex support global too early instead of validating repo-local packaging first.
Confusing plugin support with tool portability. The plugin can be portable while the real tool layer still belongs under agent-stack.

9. Prompts to hand to your agent

You can make an agent do most of this migration work for you if you ask for the right inventory first.

Audit the Claude-only surface

Audit this Claude-first plugin and identify what must be shared before we add Codex as a first-class target.

Find:
- workflow logic trapped in Claude-only commands, hooks, or manifest fields
- helper scripts that are already portable
- skills or docs that should become the shared source of truth
- packaging metadata that can stay vendor-specific

Return:
1. a shared-vs-vendor-specific split
2. the smallest safe extraction plan
3. the risks of duplicating the current tree

Design the Codex adapter

Design a Codex-first-class adapter for this existing Claude plugin without forking the workflow.

Assume:
- the real behavior should stay shared
- Codex packaging should be thin
- repo-local marketplace wiring is acceptable

Return:
1. proposed .codex-plugin layout
2. proposed marketplace.json entry
3. bootstrap and verify script plan
4. runtime smoke test plan

Turn the repo into a case-study-grade port

Take this plugin from Claude-only to Claude + Codex first-class.

Constraints:
- do not fork the behavior tree
- extract shared workflow sources first
- keep manifests thin
- add bootstrap, verify, and docs
- prefer project-local enablement first

Return:
1. a phased migration plan
2. proposed file moves
3. exact new files
4. documentation updates needed for operators

Tip: ask the agent to produce the shared-source plan and verification plan before asking it to write manifests. The mistake is usually architectural, not syntactic.