claude-engineering-plugin/docs/solutions/codex-skill-prompt-entrypoints.md

title, category, tags, created, severity, component, problem_type, root_cause

title	category	tags	created	severity	component	problem_type	root_cause
Codex Conversion Skills, Prompts, and Canonical Entry Points	architecture	codex converter skills prompts workflows deprecation	2026-03-15	medium	codex-target	best_practice	outdated_target_model

Codex Conversion Skills, Prompts, and Canonical Entry Points

Problem

The Codex target had two conflicting assumptions:

1. Compound workflow entrypoints like ce:brainstorm and ce:plan were treated in docs as slash-command-style surfaces.
2. The Codex converter installed those entries as copied skills, not as generated prompts.

That created an inconsistent runtime for cross-workflow handoffs. Copied skill content still contained Claude-style references like /ce:plan, but no Codex-native translation was applied to copied SKILL.md files, and there was no clear canonical Codex entrypoint model for those workflow skills.

What We Learned

1. Codex supports both skills and prompts, and they are different surfaces

• Skills are loaded from skill roots such as ~/.codex/skills, and newer Codex code also supports .agents/skills.
• Prompts are a separate explicit entrypoint surface under .codex/prompts.
• A skill is not automatically a prompt, and a prompt is not automatically a skill.

For this repo, that means a copied skill like ce:plan is only a skill unless the converter also generates a prompt wrapper for it.

2. Codex skill names come from the directory name

Codex derives the skill name from the skill directory basename, not from our normalized hyphenated converter name.

Implication:

• ~/.codex/skills/ce:plan loads as the skill ce:plan
• Rewriting that to ce-plan is wrong for skill-to-skill references

3. The original bug was structural, not just wording

The issue was not that ce:brainstorm needed slightly different prose. The real problem was:

• copied skills bypassed Codex-specific transformation
• workflow handoffs referenced a surface that was not clearly represented in installed Codex artifacts

4. Deprecated workflows:* aliases add noise in Codex

The workflows:* names exist only for backward compatibility in Claude.

Copying them into Codex would:

• duplicate user-facing entrypoints
• complicate handoff rewriting
• increase ambiguity around which name is canonical

For Codex, the simpler model is to treat ce:* as the only canonical workflow namespace and omit workflows:* aliases from installed output.

Recommended Codex Model

Use a two-layer mapping for workflow entrypoints:

1. Skills remain the implementation units

   • Copy the canonical workflow skills using their exact names, such as ce:plan
   • Preserve exact skill names for any Codex skill references

2. Prompts are the explicit entrypoint layer

   • Generate prompt wrappers for canonical user-facing workflow entrypoints
   • Use Codex-safe prompt slugs such as ce-plan, ce-work, ce-review
   • Prompt wrappers delegate to the exact underlying skill name, such as ce:plan

This gives Codex one clear manual invocation surface while preserving the real loaded skill names internally.

Rewrite Rules

When converting copied SKILL.md content for Codex:

• References to canonical workflow entrypoints should point to generated prompt wrappers
  • /ce:plan -> /prompts:ce-plan
  • /ce:work -> /prompts:ce-work
• References to deprecated aliases should canonicalize to the modern ce:* prompt
  • /workflows:plan -> /prompts:ce-plan
• References to non-entrypoint skills should use the exact skill name, not a normalized alias
• Actual Claude commands that are converted to Codex prompts can continue using /prompts:...

Future Entry Points

Do not hard-code an allowlist of workflow names in the converter.

Instead, use a stable rule:

• ce:* = canonical workflow entrypoint
  • auto-generate a prompt wrapper
• workflows:* = deprecated alias
  • omit from Codex output
  • rewrite references to the canonical ce:* target
• non-ce:* skills = skill-only by default
  • if a non-ce:* skill should also be a prompt entrypoint, mark it explicitly with Codex-specific metadata

This means future skills like ce:ideate should work without manual converter changes.

Implementation Guidance

For the Codex target:

1. Parse enough skill frontmatter to distinguish command-like entrypoint skills from background skills
2. Filter deprecated workflows:* alias skills out of Codex installation
3. Generate prompt wrappers for canonical ce:* workflow skills
4. Apply Codex-specific transformation to copied SKILL.md files
5. Preserve exact Codex skill names internally
6. Update README language so Codex entrypoints are documented as Codex-native surfaces, not assumed to be identical to Claude slash commands

Prevention

Before changing the Codex converter again:

1. Verify whether the target surface is a skill, a prompt, or both
2. Check how Codex derives names from installed artifacts
3. Decide which names are canonical before copying deprecated aliases
4. Add tests for copied skill content, not just generated prompt content

Related Files

• src/converters/claude-to-codex.ts
• src/targets/codex.ts
• src/types/codex.ts
• tests/codex-converter.test.ts
• tests/codex-writer.test.ts
• README.md
• plugins/compound-engineering/skills/ce-brainstorm/SKILL.md
• plugins/compound-engineering/skills/ce-plan/SKILL.md
• docs/solutions/adding-converter-target-providers.md