Codex skills: the 8,000-character budget that decides which ones load

A Codex skill is a folder with a SKILL.md in it, and its description is the only part Codex reads until the skill is selected. We read all 581 skills shipped with Codex to see what authors actually put in them. What matters, what is decoration, and where skills are discovered.

A Codex skill is a folder with a SKILL.md in it. The file has YAML frontmatter and a body of instructions, and Codex loads the body only when it decides the skill applies. Everything interesting follows from that last part.

To find out what skill authors actually do, we read every skill that ships with Codex CLI 0.147.0 on this machine: 6 system skills plus 575 bundled by the curated plugin marketplace, 581 in total. The numbers below come from that pass.

The minimum, which is also most of it

---
name: gh-fix-ci
description: Use when a user asks to debug or fix failing GitHub PR checks that run in GitHub Actions.
---

# GitHub Actions CI Fix

## Overview
...

Only two frontmatter fields are required, name and description, and the census says authors agree: all 581 skills have both. After that, consensus collapses. The next most common field, metadata, appears in 127. Then version in 82, author in 70, and a long tail of one-off keys that different vendors invented for themselves.

A few Claude Code field names show up too, since the formats are close cousins: disable-model-invocation in 12 skills, allowed-tools in 7, user-invocable in 1. The Codex binary does contain those strings, so they are not inert. But if you are writing a skill, the honest summary is that name and description do the work and the rest is convention.

The description is the product

Codex builds a list of available skills and shows it to the model with the body of each skill left out. The description is what the model sees, so it decides whether your skill is ever chosen.

There is a hard limit on that list. Per the docs, the initial skill list uses at most 2% of the context window, about 8,000 characters, and when you have many skills installed, descriptions get shortened first. Your carefully written description is not guaranteed to arrive intact.

Across the 581 skills, the median description is 183 characters and the longest is 1,020. That long one is spending roughly an eighth of the entire shared budget on a single entry, which will cost it when the list gets trimmed.

Two practical consequences:

• Front-load the trigger. Start with when to use it, in the words a user would type. The GitHub CI skill above opens with "Use when a user asks to debug or fix failing GitHub PR checks" and that is the whole reason it gets picked.
• Say when not to use it. The docs are explicit that the description should "explain when this skill should and should not trigger". With dozens of skills installed, the negative half is what stops the wrong one from winning.

This is the same economics we described for Claude Code skills, and Codex's published budget makes it concrete.

Where skills are discovered

The documentation lists these locations, most specific first:

One wrinkle worth knowing before you go hunting: on this machine the system skills are installed under ~/.codex/skills/.system, marked with a .codex-system-skills.marker file, and the CLI binary also contains the string .codex/skills. So .agents/skills is what the docs tell you to write, and .codex/skills is a path the tool also knows about. If a skill you placed by hand is not showing up, try the other location before assuming your frontmatter is wrong.

Plugins are the fifth source in practice. Of the 180 plugins in the curated marketplace, 72 bundle skills, which is where 575 of our 581 came from. Installing one plugin can add a dozen entries to that 8,000-character list, which is the context cost of plugins that the marketplace listing does not show you.

Invoking one on purpose

Implicit invocation is Codex matching your request against descriptions. Explicit invocation is you naming it: $skill-name in the Codex CLI, and @skill-name in ChatGPT.

To make a skill explicit-only, set allow_implicit_invocation: false. That setting lives in agents/openai.yaml, not in the frontmatter, which is also where a skill declares dependencies such as an MCP server it needs:

dependencies:
  tools:
    - type: "mcp"
      value: "serverName"
      url: "https://..."

The full skill folder can hold more than the one file:

my-skill/
├── SKILL.md          required
├── scripts/          optional executable code
├── references/       optional documentation
├── assets/           optional templates
└── agents/
    └── openai.yaml   optional UI config and dependencies

107 of the 581 skills bundle a scripts/ directory. That is the pattern worth copying: the SKILL.md explains the decision-making, and a script does the mechanical part deterministically, rather than asking the model to reproduce a long command correctly every time.

The six skills Codex already ships

Codex installs its own system skills, and most people never look at them:

• skill-creator, for writing a new skill
• plugin-creator, for packaging one into a plugin
• skill-installer, for installing skills
• review-agent, a read-only, defect-first code review
• openai-docs, for looking things up
• imagegen

review-agent's own instructions are a good example of what a tight skill looks like. It states its constraints in the first paragraph: do not modify files, create commits, push branches, post review comments, or delegate the review. Then it starts by reading the applicable AGENTS.md. That last detail is the relationship between the two mechanisms in one line.

Skills versus AGENTS.md

AGENTS.md is always in context and describes your project. A skill is loaded on demand and describes a procedure. The test is the same one we use for CLAUDE.md: if it is a fact Codex needs in every session, it belongs in AGENTS.md. If it is a procedure that matters only when you are doing one particular kind of task, it belongs in a skill, where it costs a description until the day it is needed.

Writing one that gets used

1. Start from a real repetition. The third time you paste the same checklist, that is the skill.
2. Write the description last, and write it as a matching rule with both halves: when to trigger, when not to.
3. Keep it near the median. 183 characters is what the working examples use. Budget accordingly.
4. Put deterministic steps in scripts/. A fifth of the shipped skills do this.
5. Test it by asking indirectly. If you have to name the skill to get it, the description is the thing to fix, not the body.

Skills are the one extension point where the cost is paid in attention rather than tokens: every skill you install makes every other skill slightly less likely to be selected. Install a plugin because you want its skills, not because the listing looked useful, and delete the ones you have never seen fire.