Codex gives contradictory invocation guidance for skill-only plugins across CLI and Desktop.

What version of the Codex App are you using (From “About Codex” dialog)?

26.803.10989.0

What subscription do you have?

plus

What platform is your computer?

_No response_

What issue are you seeing?

The main issue is contradictory invocation guidance between Codex surfaces.

Codex explicitly told me that plugin mounting/selection is not sufficient and that $skill invocation is mandatory.

That guidance appears correct for Codex CLI, where:

$codex-team <task>

works as expected.

However, on Codex Desktop, the observed behavior is different:

• $codex-team is not exposed in the Desktop session's host skill list.
• Codex reports the skill as unavailable.
• The plugin itself, "Codex Team Orchestrator", is visible and selectable in the Desktop plugin UI.
• When I explicitly select the plugin or invoke @Codex Team Orchestrator, the workflow can reach my actual framework execution path.

This creates a direct contradiction between the invocation guidance provided by Codex and the actual behavior of the Desktop product.

The main issue is contradictory invocation guidance between Codex surfaces.

Codex previously instructed me that a skill packaged in my plugin must be invoked using:

$codex-team <task>

and that merely selecting/attaching the plugin would not invoke the skill.

That guidance appears correct for Codex CLI, where $codex-team works.

However, on Codex Desktop, the opposite behavior is observed:

• $codex-team is not exposed in the Desktop session's host skill list.
• Codex reports the skill as unavailable.
• The plugin itself, "Codex Team Orchestrator", is visible and selectable in the Desktop plugin UI.
• When the plugin is explicitly selected or invoked through @Codex Team Orchestrator, the workflow can reach my actual framework execution path.

This creates a direct contradiction between the invocation guidance provided by Codex and the behavior of the Desktop product.

What steps can reproduce the bug?

Environment:

• Windows
• Codex Desktop
• Session source reported as: vscode
• Personal plugin: Codex Team Orchestrator
• Plugin contains skill: codex-team
• Plugin is installed and enabled
• PII and local filesystem paths are redacted below

Steps:

1. Create/install a personal skill-only plugin that contains a skill named codex-team.

1. Register/install it for Codex.

1. Start a fresh Codex CLI session.

1. Run:

$codex-team execute a minimal read-only smoke task

1. Observe that Codex CLI discovers the skill successfully.

In my case the CLI path successfully executed:

ExecutionPlan
→ RouteResolver
→ RunCoordinator
→ external Worker Runtime

So the plugin and skill itself are functional.

1. Open Codex Desktop.

1. Confirm that "Codex Team Orchestrator" is visible in the Plugins UI and can be selected.

1. Start a new Codex Desktop session.

1. Enter:

$codex-team execute a minimal read-only smoke task

1. Observe that Codex reports that $codex-team is not available and starts attempting an equivalent native workflow instead.

1. In the same Desktop surface, select or mention:

@Codex Team Orchestrator

1. Run a minimal task again.

1. Observe that the plugin can now participate in the request, despite $codex-team previously being reported unavailable.

Diagnostics from the affected Desktop session:

• Originator: Codex Desktop
• Source: vscode
• plugins_instructions: false
• Plugin visible in Desktop UI: YES
• Filesystem skill installed: YES
• codex-team present in host_skills: NO
• Reload required: NO

Session ID:
[Not available]

Token limit usage:
Not applicable / not observed.

Context window usage:
Not applicable / not observed.

The issue is reproducible without any project-specific code. A minimal skill-only personal plugin with one skill should be sufficient.

What is the expected behavior?

Codex should provide consistent and surface-aware invocation guidance for installed plugins and their skills.

One of the following behaviors would be acceptable:

Option A:
If a skill contained in an installed Desktop plugin is intended to be callable with $skill, Codex Desktop should expose that skill consistently so that:

$codex-team <task>

works just as it does in Codex CLI.

OR

Option B:
If Codex Desktop intentionally uses plugin selection / @PluginName rather than $skill for this type of plugin, Codex should clearly tell the user that the invocation method differs by surface.

For example:

"Codex Team Orchestrator is installed as a Desktop plugin. Use @Codex Team Orchestrator or select it from the Plugins UI. $codex-team is the CLI skill invocation and is not available in this Desktop session."

Codex should not say that the capability is unavailable when the plugin is visibly installed and selectable.

It should also not silently fall back to native Codex multi-agent behavior when the user explicitly requested an installed custom orchestrator.

For skill-only plugins, the absence of an exposed app/tool should also not be presented as if the plugin itself failed to load.

Codex should not tell users that $skill is mandatory if the active surface expects a plugin to be invoked through plugin selection or @PluginName.

The assistant should first identify the current surface and provide the correct invocation method for that surface.

Additional information

I originally spent significant time debugging this as a plugin installation / skill discovery problem because both Codex and ChatGPT repeatedly suggested using:

$codex-team <task>

That advice was correct for Codex CLI, but not for my actual Codex Desktop workflow.

I verified all of the following:

• Plugin source exists and is valid.
• Plugin is installed and enabled.
• Filesystem skill is installed.
• Fresh Codex CLI sessions discover codex-team.
• $codex-team works in Codex CLI.
• Codex Desktop visibly lists "Codex Team Orchestrator" in the Plugins UI.
• Codex Desktop allows the plugin to be selected.
• The affected Desktop session does not expose codex-team in host_skills.
• Reinstalling the filesystem skill does not change this.
• Restarting/reloading is no longer reported as required.
• Selecting / mentioning the plugin on Desktop is the path that actually reaches the plugin workflow.

This appears to be primarily a surface/invocation consistency and UX/documentation issue rather than a failure of the plugin itself.

A clearer distinction between these concepts would help:

• CLI local skill invocation ($skill)
• CLI plugin
• Desktop plugin
• Desktop host skill
• @PluginName invocation
• Plugins/Sources selection

It would also be helpful if Codex detected the active surface before suggesting $skill syntax.

I can provide screenshots showing that "Codex Team Orchestrator" is visible and selected in the Desktop Plugins UI while $codex-team is still unavailable to the session.

No credentials, API keys, private repository names, or private project content are included in this report.

The confusing part is that this was not only my assumption: Codex itself explicitly instructed me that selecting/attaching the plugin was not sufficient and that I must use $skill. That advice led me to spend significant time debugging installation, filesystem skill discovery, session reload, and host skill visibility, even though the Desktop plugin was already installed and selectable.