46 of 84 skill descriptions were reaching the model cut short

When you use skills in Codex, the model receives a skill list at the start of every conversation. The list has one line per skill: its name and description. The model reads these descriptions to decide "is this the moment to use this skill?" The description is effectively what triggers the skill.

This list has a fixed amount of room. Codex gives the skill list only 2% of the context. With few skills that is fine, but as they pile up, the room runs out. Then the end of each description gets cut off to make them fit.

Why the cut matters

A skill description usually starts with "what this skill does" and ends with "when to use it, and when not to." The cut takes the end. In other words, when to use it is the first thing to go.

The model still knows the skill exists, but it loses the grounds for deciding whether now is the time to use it. It may fail to call the skill when needed, or call it at the wrong moment.

On my computer, this was actually happening.

Measuring it

Astra Xray is a skill that computes and shows the skill list and instructions Codex hands to GPT-6 Astra. The rules for building the list are ported line by line from the relevant part of the Codex 0.154.0 source. Comparing its output with the skill list recorded in a real session log, 84 of 84 lines matched. It is not a guess; it is the same as what Codex actually sends.

• Mac: of 84 installed skills, 46 were being sent with their descriptions cut off partway. All 64 that remained after cleanup now arrive with their full descriptions.
• Windows: I trimmed the descriptions of 9 personal skills to half their length, from 2,939 characters to 1,452. Popular skills made by other people were left alone.
• Tokens: about 300 tokens fewer on every call.

Not a tool for saving money

300 tokens comes to about $4 a month at GPT-6 Astra API prices. Since the skill list is only 2% of the context to begin with, no tool can save more than that here.

The point of this tool is not cost but getting the model to read skill descriptions to the end. Where tokens really go is elsewhere: output returned by tools and skill bodies. That is measured with Codex Token Xray.

The cleanup steps

A run goes through four steps.

1. Show what is being sent now. Find cut-off descriptions, overlapping skills and instructions written for older models.
2. Show what will change and why, and get approval first.
3. Back up the files to be changed as a zip. If you do not like the result, you can restore it at any time.
4. After the changes, inspect again and compare before and after.

Rules for shortening descriptions

I set a few principles for editing descriptions.

• Shorter is not success. Keep the conditions that trigger the skill and the cases where it should not be used ("only when read-only", "only for this file type" and so on). Remove explanations the body already repeats, long lists of examples and persuasive lines like "always use this skill."
• There is no character target. Wordy descriptions get reviewed even when there is room to spare, and long ones get a second look even if they were not cut.
• The tool does not write replacement text on its own. Replacement wording is written in a plan file with the reason and reviewed, and the tool changes only the description part of the file, exactly. It backs up the original bytes before changing anything and checks the written result again.
• Every candidate is recorded. Changed, kept for a reason, excluded as someone else's skill, or decision deferred: each one is logged.

What it does not touch

The most important thing for a cleanup tool is "what it does not fix."

• Codex built-in skills and plugins (computer-use, sites and so on) are not edited.
• Skills made by other people are not edited, even if they were copied into your folder. An update would erase the edits, and the result could drift from what the author intended. If authorship is unclear, the default is to leave it and wait for confirmation.
• Model, approval, sandbox and MCP settings are outside the cleanup.
• Rules about production environments, passwords, deployment, costs and irreversible actions are never deleted. The wording can be tightened, but the behavior the rule protects must keep being protected. A rule is not treated as outdated and deleted just because it contains the word "never." Such rules often came from a real incident.

To try it

npx skills add Seokwoooo/astra-xray

Type $astra-xray in the Codex input box and it only inspects first. Cleanup happens only when you ask for it separately. It needs Python 3.9 or later, and inspection results and backups are kept only under ~/.astra-xray.

With a dozen or so skills, this problem rarely happens. If installing tools has grown your skills into the dozens, it is worth checking once what is being cut.