Codex says your skill descriptions were shortened

Symptom

Codex CLI prints this at the start of a session:

⚠ 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.

Nothing fails. Sessions run. It is easy to ignore.

Cause

Codex loads the name and description of every enabled skill into the start of each session, so the model knows what it can reach for. The skill body is not loaded. Only the description is, and it is loaded every time.

That list has a fixed budget. Install enough skills and the descriptions alone push past it.

Count what you actually have:

c=0; for d in ~/.agents/skills/*/; do [ -e "$d/SKILL.md" ] && c=$((c+1)); done; echo $c

Use the loop, not find -L ... -maxdepth 2 -name SKILL.md. Skill trees are often symlinks pointing at other symlinks, and find silently skipped three of mine. Dropping -maxdepth overshoots instead, counting nested SKILL.md files that belong to bundled sub-skills.

On my machine that returned 160 skills carrying 52,861 characters of description, or roughly 13,000 tokens spent before I typed anything. The warning appeared the same day I installed a 52-skill pack.

Why this matters more than the wording suggests

The message reads like a courtesy. It is the second of four states, and the binary contains all four:

The description is how the model decides whether a skill applies. Truncate it and selection gets worse. Remove it and the model has a name and nothing else. Reach state 4 and the skill is not merely unhelpful, it is invisible, and the model will happily do the work by hand instead.

States 3 and 4 do not announce themselves the way state 2 does. Treat the shortening warning as the last loud rung on the ladder, not as noise.

Fix

Turn off the skills you do not use. Each one is a block in ~/.codex/config.toml:

[[skills.config]]
path = "/Users/YOUR-USERNAME/.agents/skills/some-skill/SKILL.md"
enabled = false

Use the absolute path to the SKILL.md file, not the directory. Repeat the block per skill. Restart the session to see the effect.

Find your worst offenders first, since a handful of long descriptions usually carry most of the weight:

for f in ~/.agents/skills/*/SKILL.md; do
  n=$(awk 'NR>1 && /^---[[:space:]]*$/{exit}
           /^description:/{f=1; sub(/^description:[[:space:]]*/,"")}
           f && /^[a-z_]+:/ && !/^description:/{exit}
           f' "$f" | wc -c)
  printf "%6d  %s\n" "$n" "$(basename $(dirname $f))"
done | sort -rn | head -20

The exit conditions matter. A naive version that only looks for ^description: keeps matching into the body and reports the size of the whole file, which made my worst skill look like 66,518 characters instead of 1,133.

My real top entry was 1,133 characters for one skill. Three sentences would have done the same job.

Two traps

Duplicate skill trees. Codex reads ~/.agents/skills and ~/.codex/skills. If both are symlink farms pointing at the same source, you pay for the same skill twice. Check the overlap:

comm -12 <(ls ~/.agents/skills | sort) <(ls ~/.codex/skills | sort) | wc -l

99 of mine overlapped. Point one tree at the other and the bill halves.

Plugins count too. The warning names plugins alongside skills for a reason. Bundled plugins register skills you never chose.

Do not fix it by writing shorter descriptions everywhere

Tempting, and mostly wrong. The description is the only thing the model reads when deciding whether a skill is relevant. Cutting it to save budget makes every skill slightly harder to select correctly.

Delete the skills you do not use. Keep the descriptions of the ones you keep sharp and specific. A skill you never invoke costs you on every single session.