Skip to content

Curated plugin skill descriptions should be linted to fit the skills metadata budget #19957

Closed as not planned

Description

@aldegad

Summary

Several first-party plugin skills ship long frontmatter description fields. Codex renders loaded skill descriptions into the model-visible Available skills metadata block, which is capped by the skills metadata budget. Long first-party descriptions can therefore consume a large share of that budget and contribute to truncation warnings before user/project skills have much room.

This is related to #19679 (make the budget configurable) and #19090 (truncation effects), but this issue is about catalog hygiene: curated/runtime/bundled plugin skill descriptions should be concise and CI-linted.

Environment

  • Codex CLI: codex-cli 0.125.0-alpha.3
  • OS: macOS
  • First-party plugin cache roots inspected: openai-curated, openai-primary-runtime, openai-bundled
  • Note: openai/plugins appears to be the repo referenced by several curated plugin manifests, but Issues are disabled there, so I am filing this in openai/codex.

Observed

A session with local/project skills plus first-party plugin skills produced:

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

Local audit of only first-party plugin SKILL.md frontmatter descriptions found:

  • 25 plugin skills
  • 7,908 total description characters
  • 19 descriptions over 220 characters

Largest examples:

775  openai-curated/hugging-face/6807e4de/skills/vision-trainer/SKILL.md
629  openai-curated/hugging-face/6807e4de/skills/llm-trainer/SKILL.md
561  openai-curated/hugging-face/6807e4de/skills/jobs/SKILL.md
429  openai-curated/gmail/6807e4de/skills/gmail/SKILL.md
393  openai-curated/hugging-face/6807e4de/skills/transformers.js/SKILL.md
387  openai-curated/github/6807e4de/skills/gh-address-comments/SKILL.md
346  openai-curated/google-calendar/6807e4de/skills/google-calendar/SKILL.md
319  openai-curated/hugging-face/6807e4de/skills/papers/SKILL.md
314  openai-curated/hugging-face/6807e4de/skills/trackio/SKILL.md
297  openai-curated/hugging-face/6807e4de/skills/community-evals/SKILL.md
293  openai-curated/google-calendar/6807e4de/skills/google-calendar-group-scheduler/SKILL.md
288  openai-curated/google-calendar/6807e4de/skills/google-calendar-meeting-prep/SKILL.md
284  openai-primary-runtime/documents/26.423.10653/skills/documents/SKILL.md
264  openai-curated/gmail/6807e4de/skills/gmail-inbox-triage/SKILL.md
260  openai-curated/google-calendar/6807e4de/skills/google-calendar-daily-brief/SKILL.md

In the same local setup, trimming only repo-owned/custom skill descriptions reduced total skill-description payload from about 15,822 chars to about 13,992 chars and stopped the warning in a fresh codex exec smoke run. That workaround is fragile, though: first-party plugin descriptions still dominate a large part of the loaded metadata block and can reintroduce the warning as plugin catalogs grow.

Expected behavior

First-party skill frontmatter descriptions should be short routing metadata, not mini documentation. Long procedure details can stay in the skill body where progressive disclosure already applies.

Suggested fix

  • Add a packaging/CI lint for first-party plugin skill description length, for example 160-220 chars per skill.
  • Add an aggregate budget check for the default enabled plugin set so the catalog does not exceed the metadata budget by itself.
  • Keep description focused on trigger/routing signals; move detailed capability lists and workflow instructions into the body.
  • Optionally split metadata into shortDescription / routing fields if long marketplace descriptions are needed elsewhere.

This would complement #19679: even if users can configure a larger budget, the shipped first-party catalog should stay compact by default.

Activity

  1. added
    enhancementNew feature or request
    CLIIssues related to the Codex CLI
    skillsIssues related to skills
    contextIssues related to context management (including compaction)
    on Apr 28, 2026
  2. removed
    CLIIssues related to the Codex CLI
    contextIssues related to context management (including compaction)
    on Apr 28, 2026
  3. etraut-openai commented on Jul 1, 2026

    @etraut-openai
    Contributor

    This feature request hasn't received enough upvotes, so it is being closed automatically. If you still feel this feature is needed, please open a new feature request with an updated title and description.

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

    enhancementNew 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