What the documented context budget covers
Codex starts with a compact list of Skill names, descriptions, and file paths. OpenAI documents a default budget of at most 2% of the model’s context window; if that window is unknown, the list is capped at 8,000 characters. Those are different units, so do not read 8,000 characters as 8,000 tokens.
If many Skills are installed, Codex shortens descriptions first. With a large set, it may omit some entries from the initial list and show a warning. This is a discovery-list budget, not a published maximum number of installed Skills.
Installed, discoverable, and selected are different states
Installing a Skill makes its folder available in a supported location. Codex first uses the Skill’s metadata to decide what is relevant; when it selects a Skill, it reads that Skill’s full SKILL.md instructions. The selected instructions still use context during that run, but the full contents of every installed Skill are not automatically loaded just because the folders exist.
You can select a Skill explicitly with /skills or by mentioning it as $skill-name. For automatic matching, keep the description short, specific, and front-loaded with the task it handles; that matters even more if Codex needs to shorten the list.
| Stage | What Codex needs | What it means for you |
|---|---|---|
| Installed | A Skill folder in a supported location | It is available, but not necessarily used in every task. |
| Initial list | Name, description, and path within a bounded budget | Very long or overlapping descriptions are harder to discover when the list is crowded. |
| Selected for a task | The full instructions for that Skill | The active Skill’s instructions now matter to the current run’s context and behavior. |
A practical starting point: one to three distinct roles
This is an editorial starting heuristic, not an OpenAI limit or a measured performance benchmark: begin with one Skill for a workflow you repeat, then consider a small set of two or three only if each covers a different stage. For a frontend task, that might mean one Skill for visual direction, one for a design-guidelines review, and one for browser-based behavior checks.
Do not install all three just because the example lists them. The right stack depends on your project, the trust you place in each source, and whether you will inspect the output. A Skill that is rarely used, duplicates another, or asks for broader access than its job needs is a candidate to leave out.
If a Skill is missing or the list shows a warning
First check that the Skill is in a Codex-supported location and has valid name and description metadata. Then look for duplicate jobs, unusually long descriptions, and Skills you no longer use. Put the key trigger words and task boundary near the start of each description so it remains useful if shortened.
Codex also documents skills.max_context_tokens for changing the initial-list budget, up to 10,000 tokens. Treat this as an advanced configuration option, not a reason to keep every package: a larger discovery budget can use more of the context available to the session, while removing redundant Skills often makes the list clearer. Check the current configuration reference before changing it.
A simple curation rule
Keep a Skill when you can name the recurring task it handles, explain what distinct output it adds, and review its source and permissions. Start small; add or remove Skills based on real use rather than a target count.
The exact number that fits is not universal. Context size, description length, configuration, installed locations, and the task all affect discovery and use. The official documentation describes the budget behavior, but it does not promise a universally reliable maximum Skill count or a quality threshold.