The 9 Codex Skills That Earn Their Context

A Codex skill is a folder with a SKILL.md inside: YAML frontmatter plus instructions the agent loads only when your task matches. OpenAI shipped them as an experimental feature in December 2025. At session start Codex reads nothing but each skill's name and description, capped at 2% of the context window per the constants in the Codex source.

Updated August 17, 2026 · by the AITerm team

What are Codex skills?

A skill is a directory holding a SKILL.md file, plus optional scripts/, references/ and assets/ folders. Codex reads the frontmatter of every installed skill when a session starts, then loads the full instructions only for the one it decides to use. OpenAI released the feature as experimental in December 2025.

The problem Codex skills solve is boring and universal. You have a way you want a job done, you explain it in a prompt, and the next session has never heard of it.

Skills move that explanation into a file on disk. Same instructions, every session, no paste.

Here's the thing that makes them different from a bigger AGENTS.md. Skills are conditional: a memory file is in the context on every turn whether or not it is relevant, while a skill sits dormant until its description matches what you asked for.

That is progressive disclosure, and it is the whole design of Codex skills.

You're probably thinking this is just a prompt library with extra steps. Partly, yes. The difference that matters in practice is that a skill can carry executable scripts and reference documents next to the instructions, so the agent gets a procedure rather than a paragraph.

Where does Codex look for skills?

Three directories, scanned in a defined order. Repository skills live in .agents/skills/<name>/SKILL.md, personal skills in ~/.agents/skills/<name>/SKILL.md, and admin skills in /etc/codex/skills/<name>/SKILL.md. For the repository scope, Codex walks every directory from your working directory up to the repository root, which is what makes narrower skills possible in a monorepo subpackage.

Honestly, this is where most people lose an afternoon. The community catalogs still tell you to copy folders into $CODEX_HOME/skills, which resolves to ~/.codex/skills, and the awesome-codex-skills README says exactly that today.

It is not malice. The convention moved and the READMEs did not.

The evidence trail is public. In openai/codex issue 9752, filed on 23 January 2026 against version 0.89.0, a user reports that project skills in .codex/skills stopped appearing in /skills while home directory skills still showed up.

Issue 22869, filed in May 2026, describes discovery from ~/.agents/skills as the reference behaviour any new configurable directory should copy. Read those two together and the direction is not ambiguous.

So, one rule that saves you the search. If a guide tells you to use .codex/skills, it was written before spring 2026 and you should distrust the rest of it too.

Anatomy of a SKILL.md file

The file opens with YAML frontmatter between two lines of three dashes, carrying at minimum a name and a description. Everything after the closing dashes is markdown that Codex reads once it has selected the skill. That is the entire contract, and the shortest useful skill is about fifteen lines.

Here is a real one from this repository, trimmed for width. It exists because Codex kept running swift build directly and missing the signing step that our own script handles.

$ cat .agents/skills/build-aiterm/SKILL.md

---
name: build-aiterm
description: Build and sign the AITerm macOS app from source. Use when
  the task is to compile, run, package or verify the app builds after a
  Swift change. Do not use for the website in site/.
---

# Build AITerm

Always use ./build.sh. Never call swift build directly: the script
handles code signing and the .app bundle layout.

1. Run ./build.sh from the repository root.
2. On failure, read the first Swift error only. Later errors are
   usually cascades from the first.
3. Localisation strings live in Sources/AITerm/Localization/. A new
   L("key") must exist in all 7 language files or the build is a lie.

## Verifying
Open AITerm.app once and confirm the window renders before reporting
success.

Look, read that description again. It says when to use the skill and when not to, in plain sentences, with the words a developer would actually type. That is deliberate, because the description is the only thing Codex sees before it decides.

The instructions body is where people over-write. Ours is short on purpose: three numbered steps and one verification rule. A skill that reads like a wiki page burns context every time it fires, and it fires on tasks where you wanted speed.

In practice the last line does more work than the rest combined. Without it, Codex reported success on a build that produced a bundle nobody had opened. Twice.

The official catalog moved twice this year

If you followed a tutorial that sends you to github.com/openai/skills, you will land on a deprecation notice pointing at the OpenAI plugins repository instead. The deprecation pull request went up on 16 June 2026. The catalog still works, the skill-installer still pulls from it, but it is no longer where OpenAI puts new examples.

The plugins repo reorganises the same idea around a manifest. Each plugin sits at plugins/<name>/ with a required .codex-plugin/plugin.json, and a skills/ folder is one of the optional surfaces alongside .mcp.json, commands and hooks. A skill-only plugin is a legitimate shape, which is the migration path for anything you had in the old catalog.

And yes, that repo carries a read-only archive banner as of mid-August 2026, so check both before you build tooling on top of either. Two moves in three months on the canonical location of a feature tells you how young this is. Turns out the format stabilised faster than the distribution did.

The nine skills we keep installed

These are the Codex skills that survived on this repository after two months. The selection criterion was blunt: does it change what the agent does, or does it just rephrase what we would have typed anyway. Six came from the community catalogs, three are ours.

Honestly, we started with about twenty. Eleven were deleted within a fortnight, not because they were bad but because we never reached for them, and each one was still costing description budget at every session start.

Two more nearly made it. mcp-builder is excellent if you are writing MCP servers and pointless if you are not, and changelog-generator does a job we already do by hand in French. So, install what matches your week rather than what tops a list, including this one.

The honest caveat on all nine: a skill is instructions, not capability. None of these make the model better at Swift. What they do is stop you re-explaining the same procedure, which is a real saving and a smaller one than the marketing around skills implies.

How do you install a Codex skill?

Three routes to install Codex skills, and the one you pick depends on whether the skill comes from the OpenAI catalog, from a public repository, or from your own head. All three land as a folder on disk, and all three need a fresh session afterwards, since discovery runs at session start.

# 1. From inside Codex, the curated catalog
$skill-installer gh-address-comments
$skill-installer install the create-plan skill from the .experimental folder

# 2. From your shell, any public repo with a SKILL.md at its root
npx skills add vercel-labs/agent-skills --skill skill-creator
npx skills add owner/repo -a codex -a claude-code

# 3. By hand, for something you wrote yourself
mkdir -p ~/.agents/skills/build-aiterm
$EDITOR ~/.agents/skills/build-aiterm/SKILL.md

# then, in every case
/skills            # list what the current session can see
$build-aiterm      # force one explicitly instead of waiting for a match

Here's the thing about route two: it is newer than most of the guides ranking for this query. The vercel-labs/skills CLI is a cross-client installer: one command targets Codex, Claude Code, Cursor, OpenCode, Gemini CLI, Copilot, Windsurf and a dozen others, and any public GitHub repo with a SKILL.md at its root counts as a valid source. If you run more than one agent, this is the route that stops you maintaining two copies of the same instructions.

In practice we use all three. The catalog for anything OpenAI curates, npx skills for community work we want in both Codex and Claude Code, and a hand-written folder in .agents/skills for the four things specific to this codebase.

Writing your own against a 2 percent budget

Every skill you install costs context before it does anything. Codex reserves 2% of the model context window for the metadata list, or 8,000 characters when the window is unknown. Those are the constants SKILL_METADATA_CONTEXT_WINDOW_PERCENT and DEFAULT_SKILL_METADATA_CHAR_BUDGET in codex-rs/core-skills/src/render.rs, and openai/codex issue 19679, opened on 26 April 2026, asks for them to be configurable.

Cross the budget and Codex does not fail loudly. It shortens your descriptions first, then omits skills from the list entirely, with a warning that reads "Exceeded skills context budget of 2%." A skill omitted from the list is invisible to implicit matching. It is still there, and the agent will never think of it.

So the discipline is short descriptions, not fewer skills. Write the trigger, not the title. Turns out that constraint improves matching as much as it saves tokens, which we did not expect.

# Bad: describes the skill to a human
description: A comprehensive utility for handling the various tasks
  involved in the build process of the application, including
  compilation, signing and packaging steps as required.

# Good: tells the model when to fire, and when not to
description: Build and sign the macOS app. Use when compiling, running
  or packaging after a Swift change. Not for the website in site/.

The good version is 130 characters against 200, and it fires reliably where the first one competed with three other build-adjacent skills. Multiply that by twenty skills and you have bought yourself headroom you did not have.

Fair question: how many Codex skills is too many? We stopped counting and started measuring.

Run /skills in a fresh session and check whether everything you installed appears. If something is missing, you are over budget, and the fix is the prose rather than the uninstall.

Why does a skill not show up?

Four causes account for nearly all of it, and they are all silent. Wrong directory, symlinked directory, a UTF-8 byte order mark, or a session you never restarted. None of them print an error, which is why this question has its own cluster of GitHub issues.

You're probably about to rewrite the description. Don't, not yet. In practice the description is the last thing to suspect, because a badly described skill still appears in /skills and a misfiled one does not.

The BOM one is genuinely nasty. Codex checks whether the file starts with the YAML frontmatter delimiter, and a BOM means the first byte is not a dash, so a file that looks correct in every editor is treated as having no frontmatter at all. It was reported against Codex 0.111.0 and it will bite anyone editing SKILL.md on Windows.

The symlink one is documented in openai/codex issue 11314: a real .agents/skills directory loads, the same directory symlinked does not. If you keep your skills in a dotfiles repository and link them into place, that is your bug. Copy instead of linking, or script the copy.

# the four checks, in the order that finds it fastest
ls -la .agents/skills/            # real directory, not a symlink?
head -c 3 .agents/skills/*/SKILL.md | xxd | head -1   # efbbbf means BOM
head -1 .agents/skills/*/SKILL.md # first line must be exactly ---
# then quit Codex and start a new session. Discovery runs once, at start.

If all four pass and the skill still hides, you are in budget territory. Trim the longest descriptions you have and check /skills again. And if it appears in the list but never fires on its own, the description is the problem, so invoke it explicitly with $skill-name while you rewrite it.

Skills change what you have to supervise

This is the part every listicle skips, and it is the part that costs you time. Four of the nine skills above trigger a build, a test suite or a network round trip. A session that used to answer in ninety seconds now holds a pane for twenty minutes, and you have no idea when it finished unless you are looking at it.

That shift is good news, mostly. Waiting on a build you did not have to start is exactly the trade an agentic workflow is supposed to make. The catch is arithmetic: long sessions only pay off if you run several at once, and several at once means you now need to see which one is done.

Our anonymous daily ping puts the median user at around three concurrent agent sessions, with a long tail well above that. Three panes, and at least one of them running a skill that will finish in fifteen minutes without telling you. In practice, that is when people start alt-tabbing every two minutes, which costs more focus than the build ever saved.

We know how this sounds coming from the people who make a terminal, so take the claim narrowly. Nothing about skills requires a particular window. Worktrees, short descriptions and one task per session work in whatever you have open right now.

Here are our numbers instead of adjectives. AITerm is 45 MB of Swift rendering through CoreText, and with 20 panes streaming agent output it sits at roughly 140 MB of RAM on an M2 Air, where our old Electron setup reached about 1.9 GB doing the same work.

Keystroke latency stayed under 8 ms while output was heavy. The app also tracks trending Codex skills in its Radar panel, which is how we find most of what ends up on lists like this one.

Our own scar on this: the first skill we wrote ran the full test suite on every invocation, including on tasks that touched one localisation string. It was correct and it was useless, because a two-line change took eleven minutes and we stopped invoking it.

Scope your triggers narrowly. A skill you avoid is worse than no skill.

The short version: install fewer skills, write shorter descriptions, and give the long-running ones a pane you can actually see. That's it.

Going further

Sources

1. Build skills, OpenAI Codex documentation, 2026: the canonical reference for SKILL.md, progressive disclosure and the metadata budget behaviour.
2. openai/skills, Skills Catalog for Codex: the deprecation notice pointing at the plugins repository, the .system, .curated and .experimental folders, and the skill-installer usage syntax. Deprecation pull request opened 16 June 2026.
3. openai/plugins: curated Codex plugin examples, the plugins/<name>/.codex-plugin/plugin.json manifest, the optional skills/ surface, and the .agents/plugins/marketplace.json registry. Read-only archive banner observed mid-August 2026.
4. Make skills metadata context budget configurable instead of hardcoded 2%, openai/codex issue 19679, opened 26 April 2026: SKILL_METADATA_CONTEXT_WINDOW_PERCENT = 2 and DEFAULT_SKILL_METADATA_CHAR_BUDGET = 8_000 in codex-rs/core-skills/src/render.rs, plus the truncation warning text.
5. Support project-scoped personal skill discovery directories, openai/codex issue 22869, opened 15 May 2026: ~/.agents/skills/<skill-name>/SKILL.md as the reference discovery behaviour.
6. Codex does not see project-level skills anymore, openai/codex issue 9752, opened 23 January 2026 against version 0.89.0: project skills under .codex/skills disappearing from /skills.
7. Codex CLI doesn't load skills from .agents/skills when it is a symlink, openai/codex issue 11314: real directories load, symlinked ones do not.
8. $skill explicit invocation ignores local explicit-only skills, openai/codex issue 23454: the $skill-name explicit invocation path and its interaction with the implicit list.
9. awesome-codex-skills, Composio community: the community catalog behind codebase-recon, codebase-migrate, gh-fix-ci, webapp-testing, sentry-triage and skill-creator, and the README still recommending $CODEX_HOME/skills.
10. vercel-labs/skills, the open agent skills tool: npx skills add owner/repo, the --skill and -a flags, and the list of supported clients including codex, claude-code, cursor, opencode, gemini-cli, github-copilot and windsurf.
11. Introducing skills, the open agent skills ecosystem, Vercel changelog, 2026: the cross-client installer announcement and the "any public repo with a SKILL.md at its root" rule.
12. Why does a Codex skill exist in the directory but still not show up, 29 April 2026: SKILL.md files starting with a UTF-8 BOM defeating the frontmatter check in Codex 0.111.0.