Separate installed plugins from per-session skill metadata injection

[Yan-Yang-PYZNTech]

Current evidence (updated July 21, 2026)

• Independently reproduced by multiple users on macOS.
• Confirmed on Codex CLI 0.128.0 and 0.144.6.
• One independent reproduction found 14 repo-local SKILL.md files versus 83 SKILL.md files in the installed plugin cache.
• That reproduction also found skills associated with a plugin configured as enabled = false still present in the injected Available Skills list, overlapping with Config/profile disables for connectors, apps, and plugins are ignored in Codex CLI #17588.
• Increasing the metadata budget (Make skills metadata context budget configurable instead of hardcoded 2% #19679) would reduce truncation, but would not separate installed plugin availability from default per-session injection.
• Fresh CLI 0.144.6 Profile V2 A/B with the installed documents@openai-primary-runtime plugin produced documents:documents in both ON runs and removed it in both OFF runs; the first paired prompt delta was exactly 453 characters.
• Profile V2 therefore provides a partial binary per-invocation control. -c plugins.…enabled=… did not change the effective plugin state in inverse controls, and an on_demand mode that preserves explicit invocation is still missing.

What problem does this solve?

Codex currently treats enabled plugins/skills as part of the model-visible skills metadata surface for every new session. With several official plugins enabled, this can quickly hit the fixed skills metadata budget and produce warnings like:

Skill descriptions were shortened to fit the 2% skills context budget. Codex can still see every skill, but some descriptions are shorter. Disable unused skills or plugins to leave more room for the rest.

At the time of the original 0.128.0 report, the practical workaround was to disable plugins globally in config.toml. Codex CLI 0.144.6 now has Profile V2 overlays that partially improve this: a user can pre-create a profile that disables a plugin for one invocation while keeping it installed and enabled in the base configuration. This remains binary and file-based rather than an on-demand injection policy.

Why this is not only a budget-size issue

Related issues already cover important parts of this:

• Make skills metadata context budget configurable instead of hardcoded 2% #19679 asks for the hardcoded 2% budget to be configurable.
• Codex App truncates injected Available skills metadata and deterministically drops the same repo-local skills #19090 covers truncation effects in the injected Available skills metadata.
• Curated plugin skill descriptions should be linted to fit the skills metadata budget #19957 covers long first-party plugin skill descriptions.

Those would help, but there is a separate product/control-surface issue: plugin installation/enabling is currently too tightly coupled to per-session prompt injection.

For example, a user may want these different modes:

• keep a document/PPT/spreadsheet plugin installed, but not inject its skills into every normal coding session;
• start a dedicated session with those plugin skills fully injected;
• keep Browser Use or Computer Use always available;
• avoid duplicate or near-duplicate skill metadata across plugin/local/project sources;
• prioritize repo-local skills over low-frequency plugin skills when metadata budget is tight.

On current CLI, a pre-created Profile V2 overlay can switch binary plugin sets per invocation. What remains missing is a direct on_demand / manual state that keeps plugin skills explicitly available without injecting their metadata by default, plus equivalent session controls in the Codex App UI.

Requested behavior

Please consider separating plugin/skill availability from default per-session skills metadata injection. Possible designs:

• per-session or profile-based plugin sets, e.g. default, docs, browser, research;
• a config mode per plugin/skill such as inject = "always" | "on_demand" | "off" while keeping the plugin installed;
• lazy loading: inject a compact plugin/skill manifest first, then load detailed routing metadata only when the user invokes or references that capability;
• priority/pinning rules so repo-local or user-pinned skills are preserved before low-frequency plugin skills;
• automatic deduplication of identical or overlapping skill metadata across plugin/local/project roots before applying the budget;
• Codex App UI controls to start a new session with selected plugins instead of editing config.toml and restarting.

Expected result

Users should be able to keep official plugins installed without each one consuming skills metadata budget in every session. The default coding session stays compact, while specialized plugin-heavy sessions remain easy to start intentionally.

Environment

• Codex CLI: codex-cli 0.128.0
• Platform: macOS
• Scenario: multiple official plugins enabled via ~/.codex/config.toml, fresh session shows the 2% skills context budget warning.

[github-actions]

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• skill management optimizing #19911
• Support skill filtering for project-local skills.config entries #20210
• Explicit-only skills need a visible, reliable explicit invocation contract #19695

Powered by Codex Action

[Yan-Yang-PYZNTech]

Reviewed the duplicate suggestions from the bot.

• skill management optimizing #19911 overlaps with the general desire for better skill management / picker UX, but this issue is narrower: installed plugins should not automatically consume per-session skill metadata budget in every session.
• Support skill filtering for project-local skills.config entries #20210 is about project-local skills.config filtering not applying; useful and related, but it still assumes filtering/disablement as the control surface.
• Explicit-only skills need a visible, reliable explicit invocation contract #19695 is about explicit-only skill invocation and is already closed.

So I think this issue is not a duplicate of those. The specific request here is to separate plugin installation/availability from default prompt injection, with profile/lazy-load/priority/dedupe controls so users can keep plugins installed without globally disabling them or paying the full metadata cost every session.

[Yan-Yang-PYZNTech]

I took a closer look at the current implementation path and I think the fix can be scoped more narrowly than a full skill-management redesign.

Implementation roadmap

1. Separate plugin skill availability from default injection

The current coupling appears to be:

• enabled/active plugin -> plugin skill roots are included in effective_plugin_skill_roots()
• those roots are loaded into the session/turn SkillLoadOutcome
• build_available_skills() renders all enabled implicit skills into the default <skills_instructions> block, subject only to the metadata budget

A minimal control surface could be a per-plugin mode, for example:

[plugins."example@marketplace"]
enabled = true
skill_injection = "always" # always | on_demand | off

Suggested semantics:

• always: current behavior. This should be the default for backward compatibility.
• on_demand: plugin remains installed/enabled; MCP servers, apps, hooks, and plugin summaries remain available, but this plugin's skills are excluded from the default <skills_instructions> block. They become available only when the user explicitly mentions the plugin or a specific skill.
• off: plugin remains available for non-skill capabilities, but this plugin's skills are excluded from both default and explicit skill injection.

The important part is that plugin installation/enabling should no longer automatically imply default skill metadata injection in every session.

2. Split skill roots by purpose

Instead of treating all active plugin skill roots as one set, the loader/session path could distinguish:

• default-injected skill roots: used to build the normal session-visible skills list
• explicitly available skill roots: available for explicit plugin/skill mention resolution

For always, a plugin contributes to both sets.
For on_demand, a plugin contributes only to explicit availability.
For off, a plugin contributes to neither skill set, while preserving non-skill plugin capabilities.

This keeps the behavior compatible while avoiding global disablement as the only workaround.

3. Keep dedupe/priority as a complementary layer

Deduplication is related, but I do not think it is sufficient as the primary fix.

Codex already appears to have root/path-level dedupe for skill discovery and explicit mention handling. What is missing is higher-level dedupe/priority, such as avoiding semantically overlapping plugin skills or preferring repo-local/user-pinned skills when the metadata budget is tight.

That would help, but even perfect dedupe would not solve the core case where a user has many distinct plugin skills installed. Those should still not all be injected into every default coding session.

So I would treat priority/dedupe as a follow-up layer after the availability-vs-default-injection split.

4. Tests I would expect

• config parsing defaults skill_injection to always
• always preserves current plugin skill injection behavior
• on_demand excludes plugin skills from default <skills_instructions>
• explicit plugin mention makes on_demand plugin skills available for that turn
• off keeps the plugin enabled for non-skill capabilities while excluding its skills
• existing skills.config per-skill disabling still wins where applicable

This seems like a focused first step toward profile/lazy-load/priority controls without requiring the whole UX to be designed at once.

Does this match the direction the team would consider? I understand unsolicited PRs are not generally reviewed, but if this approach aligns with the intended solution, I would be happy to prepare a focused PR after maintainer confirmation.

[SylvainWinning]

Thanks for opening this. I ran into the same underlying issue while looking at skills/plugins behavior: plugin enablement currently feels coupled to default skill metadata injection.

A small MVP that might address this without changing current behavior by default:

• Keep always as the default/current behavior: enabled plugin skills are included in default skill metadata and available by explicit mention.
• Add on_demand: the plugin remains enabled and non-skill capabilities remain available, but its skills are omitted from default skill metadata and only loaded when explicitly mentioned.
• Add off: the plugin remains enabled for non-skill capabilities, but its skills are excluded from both default metadata and explicit skill injection.

This would let users keep plugins installed/enabled without spending prompt budget on every skill description in every session.

Related signals seem to point to the same underlying need:

• Skills: hard budget limit (5440 chars) with no exclude/disable mechanism causes mass description truncation #24299: hard skill metadata budget and mass description truncation
• Project-level config should support disabling global/user skills while preserving repo skills #24237: project-level control over inherited/global skills
• Dollar sign menu bloated with entirely irrelevant plugins I've never seen before or configured #24145 and Unexpected skill/plugin appearing in Codex CLI #24319: plugin/skill suggestions becoming noisy or unexpected

Possible MVP validation:

• Config parsing tests for default/current behavior plus on_demand and off.
• A test that on_demand plugin skills are omitted from default <skills_instructions>.
• A test that explicit invocation can still load on_demand skills.
• A test that off excludes plugin skills from both default and explicit skill injection.
• A regression test that existing [[skills.config]] behavior still wins for per-skill enable/disable rules.

The main design question is probably naming and surface area: whether this should be expressed as something like skill_injection = "always" | "on_demand" | "off" on plugin config, or through a more general plugin visibility/control setting.