Bundled openai-docs skill does not preserve the Codex surface and routes CLI questions to desktop-app guidance

What version of Codex CLI is running?

codex-cli 0.147.0

Platform

• Windows x64
• PowerShell
• Bundled system skill: openai-docs

What issue are you seeing?

The bundled openai-docs skill does not enforce a hard distinction between Codex surfaces such as CLI, desktop app, IDE extension, and cloud.

As a result, questions asked from Codex CLI about installing or configuring the CLI can be routed to ChatGPT/Codex desktop-app documentation and answered with GUI-specific instructions.

The relevant source appears to be:

codex-rs/skills/src/assets/samples/openai-docs/SKILL.md

The skill has a strong instruction to preserve an explicitly requested model, but no equivalent instruction to preserve an explicitly requested Codex surface or infer the current CLI surface for phrases such as "this Codex."

Minimal reproduction

1. Start Codex CLI on Windows with the bundled openai-docs skill available.

2. Ask:

   I want to uninstall all Codex installations and download/install Codex directly. Do not use npm. Show the steps.
   

3. The agent searches official documentation but routes to the Windows desktop-app pages.

4. It recommends the ChatGPT desktop MSIX/Store package and states that a standalone Windows CLI installer is not documented.

5. Clarify:

   I only want the CLI. I do not need a GUI.
   

6. After fetching the Markdown form of the official CLI page, the agent finds the actual Windows standalone installer:

   powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
   

Official CLI page:

https://learn.chatgpt.com/docs/codex/cli

Actual behavior

• The current CLI surface is not treated as a routing signal.
• General "Codex on Windows" searches frequently prioritize the desktop app.
• The agent substitutes desktop-app installation guidance for CLI installation guidance.
• The rendered HTML fetch can expose only the default macOS/Linux install tab, while the Windows installer is present in /docs/codex/cli.md. The skill has no explicit fallback for tabbed documentation.

Expected behavior

• An explicitly named surface such as CLI must be treated as a hard constraint.
• In a CLI session, "this Codex" or an otherwise unspecified local Codex installation should default to Codex CLI unless the user names another surface.
• Desktop-app guidance must not be substituted for CLI guidance.
• When a documentation page uses platform tabs, the skill should fetch its Markdown representation before concluding that a platform-specific method is unavailable.

Why the current skill definition is vulnerable

The current openai-docs skill is an umbrella for Codex setup, troubleshooting, self-knowledge, OpenAI products, and ChatGPT Work. It instructs the agent to search the exact topic, but it does not require a surface classification such as:

• CLI
• desktop app
• IDE extension
• cloud
• API/SDK

It explicitly says to preserve the requested model, but has no equivalent rule such as:

Preserve the explicitly requested Codex surface; never substitute another surface.

Suggested fix

Add a surface-routing section to the bundled skill, for example:

## Codex surface lock

Before searching, identify the target surface:
CLI, desktop app, IDE extension, cloud, or API/SDK.

- An explicitly named surface is a hard constraint.
- Preserve the explicitly requested Codex surface; never substitute another surface.
- If the user says CLI, include "Codex CLI" in every search query.
- Prefer /docs/codex/cli and pages marked surface=cli.
- Do not use desktop-app guidance as a substitute for CLI guidance.
- In a CLI session, "this Codex" defaults to CLI unless the user names another surface.
- For tabbed documentation, fetch the .md form before concluding that a platform or install method is unavailable.

Impact

This can cause users to:

• install a large GUI application they did not request;
• uninstall or replace the wrong Codex surface;
• incorrectly conclude that Windows standalone CLI installation is unavailable;
• lose confidence in answers about the tool from the tool itself.

Related issue

• #24239 concerns the same bundled openai-docs skill, but reports incorrect assumptions about Docs MCP availability. This surface-routing issue is separate.

Read codex-rs/skills/src/assets/samples/openai-docs/SKILL.md and reproduce the routing with the CLI and Windows prompts in the issue. Trace how surface selection and tabbed documentation are currently instructed. Done means explicit CLI requests remain on CLI guidance, unspecified local Codex defaults correctly in the CLI context, and Markdown documentation is considered when platform tabs hide details.