Description
OpenSpec’s Codex integration still relies on the legacy prompt / slash-command workflow (/opsx:*). However, in recent versions of Codex CLI, user-defined slash commands are no longer reliably supported or automatically registered.
Even after running:
openspec init --tools codex
openspec update --force
the generated assets still include:
containing files such as:
opsx-apply.md
opsx-propose.md
opsx-archive.md
However, these prompt files are not registered as executable slash commands in Codex CLI.
Inside Codex:
returns:
Unrecognized command '/opsx'
This indicates that the generated integration is not compatible with the current Codex runtime behavior.
Environment
- OpenSpec version: 1.3.1
- Codex CLI version: 0.133.0
- Node.js: v22.16.0
- OS: macOS
- Tool target: codex-cli
Reproduction Steps
Install OpenSpec:
npm install -g @fission-ai/openspec@latest
Initialize Codex integration:
openspec init --tools codex
openspec update --force
Inspect generated prompts:
Start Codex:
Try invoking:
Actual Behavior
Codex reports:
Unrecognized command '/opsx'
despite the presence of generated prompt files.
Expected Behavior
OpenSpec should:
- Stop generating deprecated Codex slash-command integration (
/opsx:*)
- Fully migrate to the Skills-based workflow (
$openspec-*)
- Update documentation, examples, and quickstart guides to remove or deprecate
/opsx:* usage
- Provide clear warnings or compatibility checks for unsupported Codex CLI versions
Documentation Issue (Important)
There is also a documentation-level inconsistency:
- Current documentation still describes
/opsx:* as a valid invocation mechanism
- However, Codex CLI no longer supports user-defined slash commands in a reliable or consistent way
- The Skills mechanism (
$openspec-*) appears to be the only stable supported approach
This leads to a misleading user experience where:
- Installation succeeds
- Files are generated correctly
- But commands cannot be executed in Codex
Related Issues
Summary
This issue is not only an implementation incompatibility, but also a documentation drift problem. The documentation and generated assets no longer match the actual Codex CLI runtime behavior.
Therefore, I suggest:
- Updating documentation to explicitly deprecate
/opsx:*
- Aligning all examples with the Skills-based model (
$openspec-*)
- Preventing new users from being misled into using unsupported slash-command workflows
References (Official Deprecation Evidence)
There is official confirmation that Codex has deprecated the custom slash-command / prompt-based workflow.
1. Custom Prompts (Deprecated)
OpenAI Codex documentation explicitly states that custom prompts are deprecated:
https://developers.openai.com/codex/custom-prompts
Custom prompts are deprecated.
This feature previously allowed Markdown files to be exposed as slash commands (e.g. /xxx), but is now marked as deprecated in favor of Skills.
2. Skills as Replacement Mechanism
The official Skills documentation indicates that Skills are the replacement for reusable prompt workflows:
https://developers.openai.com/codex/skills
Skills are positioned as the modern mechanism replacing:
- reusable prompts
- slash-command-style workflows
3. CLI Slash Commands Documentation
The Codex CLI documentation for slash commands only lists built-in commands:
https://developers.openai.com/codex/cli/slash-commands
There is no longer any supported mechanism for user-defined slash command registration via ~/.codex/prompts.
4. GitHub Discussion / Version Changes
Codex CLI versions ≥ 0.117.0 reportedly removed or broke support for custom prompt-based slash commands:
openai/codex#15941
This aligns with observed behavior where:
~/.codex/prompts/*.md files are no longer registered as commands- Custom
/opsx:* style invocations are unrecognized
Conclusion
These sources collectively indicate that:
- The slash-command prompt system is deprecated or removed
- Skills (
$skill-name) are the current supported mechanism
- OpenSpec Codex integration relying on
/opsx:* is therefore incompatible with modern Codex CLI behavior
Description
OpenSpec’s Codex integration still relies on the legacy prompt / slash-command workflow (
/opsx:*). However, in recent versions of Codex CLI, user-defined slash commands are no longer reliably supported or automatically registered.Even after running:
the generated assets still include:
containing files such as:
However, these prompt files are not registered as executable slash commands in Codex CLI.
Inside Codex:
returns:
This indicates that the generated integration is not compatible with the current Codex runtime behavior.
Environment
Reproduction Steps
Install OpenSpec:
Initialize Codex integration:
Inspect generated prompts:
ls ~/.codex/promptsStart Codex:
Try invoking:
Actual Behavior
Codex reports:
despite the presence of generated prompt files.
Expected Behavior
OpenSpec should:
/opsx:*)$openspec-*)/opsx:*usageDocumentation Issue (Important)
There is also a documentation-level inconsistency:
/opsx:*as a valid invocation mechanism$openspec-*) appears to be the only stable supported approachThis leads to a misleading user experience where:
Related Issues
/prompt invocation broken in Codex while $skill works)/opsx:*commands not recognized in codex-cli v0.117.0 interactive dialog #890 (/opsx:* regression)Summary
This issue is not only an implementation incompatibility, but also a documentation drift problem. The documentation and generated assets no longer match the actual Codex CLI runtime behavior.
Therefore, I suggest:
/opsx:*$openspec-*)References (Official Deprecation Evidence)
There is official confirmation that Codex has deprecated the custom slash-command / prompt-based workflow.
1. Custom Prompts (Deprecated)
OpenAI Codex documentation explicitly states that custom prompts are deprecated:
https://developers.openai.com/codex/custom-prompts
This feature previously allowed Markdown files to be exposed as slash commands (e.g.
/xxx), but is now marked as deprecated in favor of Skills.2. Skills as Replacement Mechanism
The official Skills documentation indicates that Skills are the replacement for reusable prompt workflows:
https://developers.openai.com/codex/skills
Skills are positioned as the modern mechanism replacing:
3. CLI Slash Commands Documentation
The Codex CLI documentation for slash commands only lists built-in commands:
https://developers.openai.com/codex/cli/slash-commands
There is no longer any supported mechanism for user-defined slash command registration via
~/.codex/prompts.4. GitHub Discussion / Version Changes
Codex CLI versions ≥ 0.117.0 reportedly removed or broke support for custom prompt-based slash commands:
openai/codex#15941
This aligns with observed behavior where:
~/.codex/prompts/*.mdfiles are no longer registered as commands/opsx:*style invocations are unrecognizedConclusion
These sources collectively indicate that:
$skill-name) are the current supported mechanism/opsx:*is therefore incompatible with modern Codex CLI behavior