Codex skills: how they load, where they live, and the budget nobody mentions

A Codex skill packages a workflow so you stop re-explaining it. Concretely: a directory containing a SKILL.md file whose frontmatter has a name and a description, plus any scripts or reference files it needs. Codex reads skills from .agents/skills, and you invoke one by typing $ and its name, or let Codex pick it when your task matches its description. That is the whole format, and it is genuinely small. The parts worth a page are the ones that decide whether a skill actually fires: where Codex scans, how the loading works, and the context budget that quietly caps how many skills can even be offered to the model.

What a skill is, and what loading one costs

The format is deliberately thin. A folder, a SKILL.md, frontmatter with name and description, then the instructions in Markdown underneath. Codex builds on the open agent skills standard, so the file you write is not Codex-shaped, which matters if you would rather not rewrite it later.

The mechanic that makes skills cheap is progressive disclosure. Codex starts with only each skill's name, description and file path in context. It reads the full SKILL.md only once it decides to use that skill. So a 180-line skill costs you nothing until it fires. The description is the only part that is always loaded, which reframes what a description is for: it is not a summary of the skill, it is the entire basis on which the skill will or will not be chosen.

Where Codex looks for skills

Codex scans several locations, and the repository ones stack from where you are standing up to the root. That is the behavior worth internalizing, because it is what lets a monorepo give one module its own skills without imposing them on the others:

The 2% budget, and what it costs to be greedy

Here is the constraint almost nobody writing about Codex skills mentions, and it should change what you install. The initial skill list is capped at 2% of the model's context window, or 8,000 characters when the window is unknown. That list is what Codex sees to pick from. When you exceed it, Codex shortens skill descriptions first, and for large skill sets it may omit some skills entirely and show a warning. A skill that is omitted from the list is not a skill that loads slowly. It is a skill that, for implicit invocation, does not exist.

So it is worth knowing what your set actually costs. We measured ours, because we ship a lot of them and the number was not flattering. kitstarter installs 17 skills. Their names and descriptions total 5,683 characters: 71% of the 8,000-character fallback budget, before you have added a single skill of your own. Our longest description is 483 characters, our shortest is 233.

We are publishing that because it is checkable (skills.list.mjs and the frontmatter of 17 files, all in the npm tarball) and because the conclusion is uncomfortable for us: a kit that ships 40 skills is not more generous than one that ships 17, it is eating your budget. Description length is the real currency here, not skill count, and the cap is the right constraint to design against. It is also why the budget only bites at 8,000: on a large context window, 2% is far more room. Check what your window actually is before panicking about this.

The description is the trigger, so write it like one

Codex can activate a skill two ways. Explicit: you type $name, or run /skills to browse. Implicit: Codex matches your task against the skill's description and chooses it. Implicit invocation is the one that feels like magic and the one that fails silently, and the whole difference is the description.

Two rules follow directly from how the budget works. Front-load the trigger words, because if Codex shortens your description to fit, the front is what survives. And name the boundary, not just the job: a description that says when the skill should not fire is what stops it hijacking unrelated tasks. Ours read as trigger lists rather than summaries for exactly this reason. The Codex tips skill's description names the sentences a user actually says: "what can Codex do", "is there a better way", "I didn't know Codex could do that". Those are not a description of the skill. They are the match targets, in the user's words, which is the only vocabulary that will ever be in the prompt.

Four things that will bite you

In roughly the order we hit them:

1. Duplicate names are not merged. If two skills share a name, Codex does not resolve them, and both show up in the selectors. Install a kit globally in ~/.agents/skills and again into a project's .agents/skills and you get two of everything. This is the same posture as Codex hooks, where every matching layer runs rather than the nearest one winning.
2. Skills are not slash commands. The sigil is $, not /. It is a small thing that tells you a lot about a page: anyone describing Codex skills as slash commands is writing about Claude Code with the names swapped, and probably has not run either.
3. A changed skill sometimes needs a restart. Codex detects skill changes automatically, and when an update does not show up, restarting Codex is the documented answer rather than a superstition. Changing ~/.codex/config.toml, including a [[skills.config]] entry, does require a restart.
4. You can disable rather than delete. A [[skills.config]] entry in ~/.codex/config.toml with a path and enabled = false turns a skill off without removing the folder. That is the right tool for reclaiming budget from a skill you are not using but do not want to lose.

What 17 skills for Codex actually look like

Since a worked set is more useful than another format explanation: ours install to .agents/skills for a project or ~/.agents/skills globally, exactly where Codex scans, and they are invoked as $start, $tour, $fix, $lean, $review, and so on. They are ordinary SKILL.md files with no Codex-specific dialect, because there is no such thing.

The one Codex-specific skill in the set is $codex-tips, and it is worth describing because it shows what a skill is good at that a document is not. It does not dump a feature list. It maps a friction the user just described to the one Codex feature that answers it: re-explaining project rules maps to AGENTS.md, a repeated workflow maps to a SKILL.md, a check that must run every time maps to .codex/hooks.json and a reminder to run /hooks and trust it, a noisy broad audit maps to subagents. It also tells the user something most product content will not: Codex changes fast, so /help, /hooks and /mcp are the source of truth for the exact interface in front of them, not us. A skill that is honest about its own staleness is more useful than one that is confidently out of date.

The summary: a skill is a folder and a description, the description is the trigger, and the budget is the constraint that should shape your whole set. Write fewer, describe them by their trigger words, front-load, and check `/skills` to see what Codex actually offered. If you want a set already written and installed to the right folder, that is kitstarter, one install for Codex and Claude Code. The sibling pages go deeper on wiring Codex hooks and on how Codex and Claude Code really differ, including where the kit is honestly weaker on Codex than on Claude Code.

Common questions

What are Codex skills? A skill is a directory containing a SKILL.md file whose frontmatter has a name and a description, plus any optional scripts or reference files. It packages a workflow so Codex can follow it reliably instead of you re-explaining it. Codex loads only the name, description and path up front, and reads the full instructions when it decides to use the skill.

Where do I put a Codex skill? In .agents/skills/<name>/SKILL.md. Codex scans that folder in every directory from your working directory up to the repository root, so a skill can be scoped to one module or shared across the repo. For skills you want in every project, use $HOME/.agents/skills. Admins can also place skills in /etc/codex/skills, and some skills ship bundled with Codex.

How do I use a skill in Codex? Type $ followed by the skill name to invoke it explicitly, or run /skills to browse what is installed. Codex can also choose a skill implicitly when your task matches its description, which is why the description should be written as trigger words and boundaries rather than as a summary.

How many skills can I install in Codex? There is no hard limit on installing them, but there is a limit on how many can be offered to the model. The initial skill list is capped at 2% of the context window, or 8,000 characters when the window is unknown. Past that Codex shortens descriptions, then omits skills and warns. For scale: kitstarter's 17 skills use 5,683 characters of name and description, about 71% of the 8,000-character fallback. Description length matters more than skill count.

Are Codex skills the same as Claude Code skills? The format is close, since both are a folder with a SKILL.md carrying a name and description, and both load the body only when the skill is used. The differences are the location, .agents/skills for Codex against .claude/skills for Claude Code, the sigil, $name against /name, and the published context budget on the skill list, which Codex documents and Claude Code does not.