Codex "Skill Descriptions Were Shortened" Warning — What It Means

What the warning means

Skill descriptions were shortened to fit the 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.

This exact warning means five specific things:

Codex still has one initial-list entry for every enabled skill. The current source emits this sentence only when no skill entry was omitted.
Some description text was shortened in the model-visible list. Skill names and their file paths or other locators remain in that list.
The full SKILL.md was not edited or truncated on disk. Codex still reads the full file after it selects the skill.
The combined metadata for enabled skills and plugin-provided skills exceeded its prompt budget. More skills and longer descriptions both add pressure.
Implicit selection may become less reliable. That is a risk, not a guaranteed failure: it depends on whether the retained description still distinguishes the skill from its neighbours.

The first four points are documented or confirmed by current openai/codex source. The fifth is diagnosis from the documented selection mechanism: implicit invocation matches the request against the description, so removing distinctive trigger language can remove evidence the model uses to choose.

Fastest safe actions

1. Explicitly invoke the skill you need now

Type $skill-name, use the $ picker, or run /skills and select it. Explicit invocation does not depend on Codex inferring intent from a shortened description. Once selected, Codex reads the full SKILL.md.

This is the quickest response for a task already in progress. It does not reduce future context pressure.

2. Disable unused skills without deleting them

For a local skill, use its exact SKILL.md path in ~/.codex/config.toml:

[[skills.config]]
path = "/path/to/unused-skill/SKILL.md"
enabled = false

Restart Codex after changing the file. This is the official reversible control; deleting skill directories is unnecessary. Turn off whole plugins you do not need for current work through the plugin controls as well—the warning itself names enabled plugins because their bundled skills share the same list.

Before disabling anything, check for the same skill installed in repo, user, and plugin scopes. Codex does not merge duplicate names, so two copies can consume two catalogue rows.

3. Tighten descriptions, starting with the longest

Keep the user intent, trigger phrases, file types, and important negative boundaries near the front. Move workflow detail into the body, which loads after selection.

# Costs context without improving selection
description: A comprehensive workflow containing scripts, references, templates,
  validation stages, output conventions, and detailed implementation guidance...

# Gives Codex the routing evidence first
description: Create or edit Word documents (.docx), including tracked changes,
  comments, formatting preservation, and text extraction.

Do not shorten every description blindly. A concise but generic line such as “Helps with documents” saves characters while making routing worse. The useful target is short and discriminative.

4. Disable a whole low-use plugin before many individual skills

Plugins can contribute several skills at once. If a plugin is irrelevant to ordinary coding sessions, disabling that plugin removes more catalogue pressure than trimming unrelated skills one at a time. Keep specialist plugins for specialist sessions rather than paying their metadata cost everywhere.

An open Codex issue reports that current Profile V2 overlays can predefine a session profile with a plugin disabled while leaving it installed in base configuration. That is reporter-observed issue evidence, not an official on-demand plugin workflow; use only controls present in your installed Codex version.

When it is only a warning—and when it matters

Situation	Likely effect
You invoke important skills explicitly	Usually informational. Full instructions still load after selection.
Retained text still names the exact task, file type, and trigger	Implicit selection can still work normally.
Distinguishing words or negative boundaries were late in long descriptions	Routing can become broader, weaker, or wrong. Diagnosis.
Several skills have similar names and similarly shortened descriptions	Codex has less evidence for choosing between them. Diagnosis.
Codex shows a different warning saying skills were not included in the model-visible list	Material discovery loss: some skills are no longer represented in the initial prompt.

The wording matters. “Codex can still see every skill” is a guarantee about this particular rendered list, not a guarantee that every possible oversized catalogue always fits. OpenAI's documentation says larger skill sets may eventually omit skills from the initial list and show a warning. Current source uses a separate omission warning when even the minimum name-and-locator rows do not fit.

If a skill is listed but does not trigger, continue with the agent skills not working diagnostic. A malformed or undiscovered skill is a different failure from a valid skill whose description was shortened.

How the current budget works

Documented: Codex initially exposes each skill's name, description, and file path. That list receives at most 2% of the model context window. If the context-window size is unknown, Codex uses an 8,000-character fallback. The budget applies to the initial catalogue, not to the full instructions loaded after a skill is chosen.

Current-source detail: Codex first checks whether every full metadata row fits. If not, it reserves the minimum row—name plus locator—for each skill and distributes remaining space across descriptions. If those minimum rows fit, every skill remains visible and this page's warning can appear. If the minimum rows do not fit, later entries are omitted and Codex emits a stronger warning that reports the omitted count.

The current source only displays the exact “descriptions were shortened” warning after the average removed description text exceeds 100 characters per skill. Smaller reductions can therefore happen without this sentence. That threshold controls warning visibility; it does not change the budget.

One distinction prevents bad fixes: the 1,024-character per-description limit and the combined catalogue budget are separate constraints. A description can be valid under the Agent Skills specification and still contribute heavily to the combined budget. Conversely, a description over 1,024 characters can be rejected as invalid before this budget warning is relevant. The SKILL.md validator checks that structural limit and description quality signals.

What current Codex issues do—and do not—establish

Exact warning and plugin pressure

openai/codex #21425 contains the exact warning and a reporter's reproduction with multiple enabled official plugins. It supports the practical link between enabled plugins and catalogue pressure. Its proposed “installed but on demand” mode remains a feature request, not documented product behaviour. Verified public issue; reporter observation.

A configurable budget

openai/codex #19679 asks for public configuration of the budget. The example configuration keys in that issue are proposals. Do not add them to config.toml unless current official documentation for your Codex version names them. Open enhancement request, not a documented workaround.

Skills actually omitted from the initial list

openai/codex #19090 reports a Codex App case where a repeatable tail set of repo-local skills was absent from the injected list. It is consistent with the omission state documented by OpenAI and implemented in current source, but the issue remains open and has no maintainer resolution in the public thread. Treat its counts and app-specific behaviour as the reporter's evidence, not a universal Codex guarantee. Verified public issue; unresolved reporter observation.

Long individual descriptions

In openai/codex #13941, an OpenAI collaborator confirmed that rejecting descriptions over 1,024 characters is expected because the public skills specification sets that limit and short metadata is part of the context-saving design. That maintainer statement supports shortening oversized descriptions, but it does not say every valid description should be made as short as possible. Maintainer-supported.

Known, inferred, and not claimed

Documented: progressive disclosure; name, description, and path in the initial list; 2% budget or 8,000-character unknown-window fallback; full SKILL.md loading after selection; explicit and implicit invocation; reversible skill disabling.
Confirmed in current source: this exact warning has zero omitted entries; descriptions shorten before entries disappear; a distinct warning reports actual omissions.
Diagnosis / inference: losing late trigger terms can hurt implicit selection, especially among similar skills. The mechanism supports that conclusion, but no universal failure rate is published.
Not claimed: AgentSkills.site did not reproduce this warning, measure its routing impact, or verify the open issue reports independently.

For the full loading model and scope locations, see Codex Skills: The Practical Guide. For broader discovery and triggering failures, use Agent Skills Not Working.