Plugins need declarative router-selection metadata for broad host workflows

What version of Codex is running?

Current main as of 2026-04-27.

What problem should this solve?

Codex plugins can expose many skills, MCP servers, and app connectors. For
some plugin families, broad user requests need one top-level router skill to
own the turn before more specialized skills are considered.

Today the reliable paths for activating a plugin skill are explicit user
selection, $skill mention syntax, or model interpretation of the available
skills list. Those are good for explicit invocation, but they do not give a
plugin a declarative way to say:

• this host surface is allowed to auto-select me
• these prompt or workspace signals indicate my broad router should own the

turn

• do not auto-select me if the user already selected a skill explicitly
• when matched, select this specific top-level router skill

That leaves host integrations with weaker alternatives:

• encode plugin-specific lexical routing in the host
• inject synthetic user text to force a router
• require users to manually name the router for every broad request
• hope the model infers the intended owner from available-skill prose

Desired behavior

It would be useful for a plugin manifest, or another plugin-owned metadata
surface, to support declarative router-selection metadata.

Conceptually, the metadata could describe:

• host scopes where the rule is eligible, such as desktop/app-server surfaces
• prompt signals that indicate the plugin's broad domain
• workspace markers such as files or extensions
• suppression policy when an explicit skill has already been selected
• the fully qualified top-level router skill to select

The host would consume this metadata from normal plugin load/cache state and,
when enabled for that host surface, convert a match into structured skill
selection. It should not need to synthesize user text or rediscover plugin
manifests per turn.

Non-goals

This issue is not asking Codex to:

• hardcode any particular plugin or domain into the host
• change explicit $skill invocation semantics
• auto-run plugin tools
• mutate the user's message
• make broad routing mandatory for every plugin

The ask is only for a generic contract that lets a plugin declare when a host
may select one top-level router skill for broad workflows.

Minimal validation shape

A useful validation shape would cover:

• explicit skill selection wins and suppresses automatic router selection
• a natural broad prompt can select the configured top-level router
• a non-matching prompt does not select the router
• workspace-only markers can select the router when configured
• disabled or missing target skills are not selected
• route evidence identifies the selected router independently of final answer

text

Why this belongs in plugin metadata

The plugin is the component that knows its broad entrypoint, domain signals,
and suppression policy. The host should provide the safe selection mechanism,
but it should not need domain-specific routing rules for each plugin.