Skip to content

Make skills metadata context budget configurable instead of hardcoded 2% #19679

Open

Description

@iqdoctor

What problem does this solve?

Codex currently reserves a fixed 2% of the model context window for the model-visible skills metadata list. When many skills are installed, this can produce warnings like:

Warning: Exceeded skills context budget of 2%. Loaded skill descriptions were truncated by an average of N characters per skill.

The problem is that the percentage is hardcoded and cannot be tuned by users or distributions with larger skill catalogs.

Where is it hardcoded?

On origin/main today:

  • codex-rs/core-skills/src/render.rs
    • const SKILL_METADATA_CONTEXT_WINDOW_PERCENT: usize = 2;
    • default_skill_metadata_budget(...) computes context_window * SKILL_METADATA_CONTEXT_WINDOW_PERCENT / 100.
    • budget_warning_prefix(...) also hardcodes the user-facing warning text as Exceeded skills context budget of 2%.

Relevant current code:

const DEFAULT_SKILL_METADATA_CHAR_BUDGET: usize = 8_000;
const SKILL_METADATA_CONTEXT_WINDOW_PERCENT: usize = 2;
SkillMetadataBudget::Tokens(
    window
        .saturating_mul(SKILL_METADATA_CONTEXT_WINDOW_PERCENT)
        .saturating_div(100)
        .max(1),
)
"Exceeded skills context budget of 2%."

Why this should be configurable

Different installations can have very different skill/plugin surfaces:

  • small default installs may be fine with 2%;
  • power-user or enterprise installs can have many local/project/plugin skills;
  • larger context-window models can reasonably allocate more than 2% to skill discovery;
  • some users may prefer the opposite and want a smaller budget.

Right now the only way to change this is to patch and rebuild Codex.

Requested behavior

Please expose the skills metadata budget as a configurable setting, for example one or more of:

  • skills.metadata_context_window_percent / skills.context_budget_percent in config;
  • an absolute token budget override;
  • an environment variable override;
  • dynamic warning text that reflects the effective configured value instead of always saying 2%.

Expected result

Users should be able to tune the skill metadata budget without modifying source code, and warnings should report the effective budget value.

Activity

  1. added
    enhancementNew feature or request
    CLIIssues related to the Codex CLI
    skillsIssues related to skills
    configIssues involving config.toml, config keys, config merging, or config updates
    contextIssues related to context management (including compaction)
    on Apr 26, 2026
  2. github-actions commented on Apr 26, 2026

    @github-actions
    Contributor

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

    Powered by Codex Action

  3. removed
    CLIIssues related to the Codex CLI
    contextIssues related to context management (including compaction)
    on Apr 26, 2026
  4. tstager commented on Apr 27, 2026

    @tstager

    I have the same issue and believe that the OP is correct that this behavior should be adjusted to be configurable by the user.

  5. informal-stripes-condo commented on Apr 27, 2026

    @informal-stripes-condo

    +1, I think there should be a config option for this

  6. aldegad commented on Apr 28, 2026

    @aldegad

    Adding a concrete data point from a current local catalog because it points to a companion issue, not just the configurable-budget request.

    Environment:

    • Codex CLI: codex-cli 0.125.0-alpha.3
    • OS: macOS
    • Warning observed:
    Warning: Exceeded skills context budget of 2%. Loaded skill descriptions were truncated by an average of 235 characters per skill.
    

    In that setup, trimming only local/project skill descriptions reduced total loaded skill-description payload from about 15,822 chars to about 13,992 chars and stopped the warning in a fresh codex exec smoke run. So configurability would help, but catalog-side description length also matters.

    Audit of only first-party plugin skill descriptions found:

    • 25 plugin skills
    • 7,908 total description characters
    • 19 descriptions over 220 chars
    • top examples include Hugging Face vision trainer (775 chars), LLM trainer (629), HF Jobs (561), Gmail (429), Transformers.js (393), GitHub gh-address-comments (387), and Google Calendar (346).

    I filed the plugin/catalog hygiene side separately here: #19957

    I think these two fixes complement each other:

    1. make the metadata budget configurable, as requested in this issue;
    2. keep first-party plugin frontmatter descriptions short/linted so the default catalog does not consume a large share of the budget by itself.
  7. ariccio commented on Apr 28, 2026

    @ariccio

    Yeah, wait, WTF, I need to optimize and heavily prune mine, I know, but why just truncate them!?

  8. 1Const1 commented on May 1, 2026

    @1Const1

    agreed with that affected 125 version of cli. so it looks like downgrade abilities of codex

    Need parameter for this in config

  9. TheSingular commented on May 7, 2026

    @TheSingular

    It seems they have added the ability to just shorten the skill description if it exceeds the budget now, but it has not been the same ever since they added the "budget".

  10. BinaryOutlook commented on May 11, 2026

    @BinaryOutlook

    +1

  11. Cerebrovinny commented on May 14, 2026

    @Cerebrovinny

    +1

  12. em-winterschon commented on May 19, 2026

    @em-winterschon

    The fix is simple. OAI makes it a configurable setting or people will find an alternative, especially those with their own colocated GPU infra who use Codex for specific tasks. Ignoring "power users" is a very bad idea. We will code around it and stop paying for Pro accounts if we're ignored for too long, just wait and see.

  13. JoeChen2me commented on May 21, 2026

    @JoeChen2me

    I implemented this in my fork and validated it end to end.

    Summary

    • add skills.listing_budget_fraction in config.toml
    • keep the default behavior at 0.02
    • validate the setting as a fraction in the 0.0..=1.0 range
    • thread the configured value through session/context construction
    • update the warning text so it reflects the effective configured value instead of always saying 2%
    • update schema and tests accordingly

    Validation

    • cargo fmt --all
    • cargo test -p codex-core-skills
    • cargo test -p codex-core skills_listing_budget_fraction_is_loaded_from_config
    • cargo test -p codex-core build_initial_context_emits_thread_start_skill_warning_on_repeated_builds
    • cargo test -p codex-core config_schema_matches_fixture
    • cargo test -p codex-app-server config_read_preserves_skills_listing_budget_fraction_in_additional
    • cargo test -p codex-app-server turn_start_emits_thread_scoped_warning_notification_for_trimmed_skills
    • cargo test -p codex-tui live_app_server_warning_notification_renders_message

    If the Codex team is open to an external PR for this, I can send the patch from my fork immediately.

  14. 1Const1 commented on May 21, 2026

    @1Const1

    I implemented this in my fork and validated it end to end.

    You can share with us first fork with branch

    Somebody in OpenAI - we don't know when it can happens

  15. nullbio commented on Jun 4, 2026

    @nullbio

    Please fix.

  16. 1Const1 commented on Jun 9, 2026

    @1Const1

    Claude code have setting about it in config

    skillListingBudgetFraction

    Why Codex still don't have it?

  17. Radar-Lei commented on Jun 29, 2026

    @Radar-Lei

    please add this option to the settings

  18. TheSingular commented on Jul 3, 2026

    @TheSingular

    I implemented this in my fork and validated it end to end.

    .....

    If the Codex team is open to an external PR for this, I can send the patch from my fork immediately.

    I'm not from the codex team, but please open the PR if you haven't already. That would be a great way to bring it to their attention.

  19. gtcuco-personal commented on Jul 17, 2026

    @gtcuco-personal

    Confirming this on macOS with Codex CLI 0.144.5 and a larger local/plugin skill catalog. The current session warns that skill descriptions were shortened to fit the fixed 2% budget, and there is no supported configuration key to raise it.

    A user-configurable value such as skills.listing_budget_fraction = 0.03 would solve this cleanly while preserving the 2% default. The warning should report the effective configured value. In this case, moving from 2% to 3% would provide 50% more routing-metadata space without disabling useful skills or plugins.

  20. Yan-Yang-PYZNTech commented on Jul 21, 2026

    @Yan-Yang-PYZNTech

    Related but distinct control-surface issue: #21425 tracks separating installed plugin availability from default per-session skill injection.

    A current macOS reproduction on Codex CLI 0.144.6 reported the same 2% warning, with 14 repo-local SKILL.md files versus 83 in the installed plugin cache. It also found skills associated with a plugin configured as disabled still present in the injected Available Skills list.

    Making the budget configurable here would reduce truncation. It would not, by itself, let users keep plugins installed without injecting their skill metadata into every default session, so the two changes are complementary.

  21. gtcuco-personal commented on Jul 21, 2026

    @gtcuco-personal

    Fuller reproduction on macOS, Codex CLI 0.144.5, supporting both this issue and the coupling described in #21425.

    Setup: 56 user skills in ~/.codex/skills, 33 SKILL.md files in ~/.codex/plugins/cache, 8 plugins explicitly enabled = true in config.toml.

    1. The budget warning is cwd-dependent. Running from $HOME (no repo-local skills): 66 skills injected, no warning. Running from a repo containing 52 repo-local SKILL.md files: 63 skills injected and the CLI prints "warning: Skill descriptions were shortened to fit the 2% skills context budget. Codex can still see every skill, but some descriptions are shorter."

    2. The model is never told its descriptions were shortened. The warning is CLI-side only. Asked to transcribe any truncation notice present in its own prompt, the truncated session replied there is none — the degradation is silent on the model side, so it cannot compensate (e.g. by reading a SKILL.md in full before dismissing a skill).

    3. Skills from a plugin absent from config are still injected. github@openai-curated-remote has no entry in my config.toml — nor is that marketplace declared there — yet github:github, github:yeet, github:gh-fix-ci and github:gh-address-comments appear in the injected Available Skills list. The filtering is also inconsistent: 20 openai-templates skills from the same cache directory are not injected.

    This supports treating the two fixes as complementary: a configurable budget (this issue) raises the ceiling; decoupling the installed-plugin cache from per-session injection (#21425) stops unrequested skills from spending it.

  22. pacphi commented on Sep 2, 2026

    @pacphi

    Additional evidence from an agentic-kit cross-host startup-context audit.

    Environment:

    • Codex CLI 0.152.1
    • macOS
    • runtime-observed effective session window: 258,400 tokens
    • first token-bearing request in the audited session: 25,985 tokens (10.06% of that effective window; this is total startup/request context and is not attributed solely to skills)

    The current warning is now a stronger failure mode than description shortening:

    Exceeded skills context budget. All skill descriptions were removed and 80 additional skills were not included in the model-visible skills list.
    

    Agentic-kit reduced its own fully enabled managed guidance from 29,633 to 10,175 bytes for Claude, 4,537 to 1,684 bytes for Codex machine AGENTS.md, and 13,794 to 4,656 bytes for OpenCode. That does not solve the remaining Codex-owned catalogue omission: installed skills can become undiscoverable, and the model does not receive a useful machine-readable coverage state.

    This supports the configurable budget requested here, plus two companion requirements:

    1. filter model-visible metadata by effective plugin/skill enablement before spending the budget;
    2. expose included/omitted counts and the effective budget to the model/session telemetry, not only the terminal warning.

    Agentic-kit will keep its owned projections bounded and will not patch Codex skill enumeration or installed plugin caches. A released configurable/observable host contract is the removal proof for its upstream constraint.

  23. yoavshmariahu commented on Oct 20, 2026

    @yoavshmariahu

    The configurable budget (#38978) helps, but the default still scales with the context window and is uncapped when unset: 2% of 272k = ~5.4k tokens for gpt-6-astra, ~10k for gpt-6.1-sol, re-sent on every model call. Since #46070 there's also no warning when it's large.

    Data point from a large repo (PostHog, 108 repo skills) on gpt-6-astra, 15 tasks that each depend on one specific skill. Replacing the listing with names + paths only:

    • The right SKILL.md was still read in 13/15 sessions, vs 14/15 with full descriptions.
    • Pass rate unchanged (12/15 both).
    • Session input tokens −11%.

    For comparison, on the same repo Claude Code's skill listing is already compact (removing all 108 skills changes its first-turn input by ~850 tokens), and Cursor truncates each description to ~80 chars.

    Suggestion: apply a fixed default cap (e.g. ~1–2k tokens) instead of scaling with the window, falling back to names + paths when the catalog doesn't fit.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    configIssues involving config.toml, config keys, config merging, or config updatesenhancementNew feature or requestskillsIssues related to skills

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions