The 9 Codex Skills That Earn Their Context

Codex skills are folders with a SKILL.md inside: YAML frontmatter plus instructions the agent loads only when your task matches. OpenAI shipped them in December 2025. As of October 2026, Codex lists only each skill's name, description and path at session start, capped by default at 2% of the context window.

Updated October 16, 2026 · by the AITerm team

What are Codex skills?

A skill is a directory holding a SKILL.md file, plus optional scripts/, references/, assets/ and agents/openai.yaml. Codex reads the name, description and path of every installed skill when a session starts, then loads the full instructions only for the one it picks. They run in the Codex CLI, the IDE extension and the Codex app.

The problem they 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.

Here's the thing that makes them different from a bigger AGENTS.md. A memory file sits in the context on every turn whether or not it is relevant, while a skill stays dormant until its description matches what you asked for. That is progressive disclosure, and it is the whole design.

You're probably thinking this is a prompt library with extra steps. Partly, yes. What a prompt cannot do is carry executable scripts and reference documents next to the instructions, so with a skill the agent gets a procedure rather than a paragraph.

One disambiguation, because Google mixes them up. The page at docs.codex.io that ranks for this query belongs to a different company called Codex, a blockchain data API, and describes a skill that teaches agents its GraphQL queries. Unless you work with on-chain data, nothing on it applies to you.

Where does Codex look for skills?

Four scopes, scanned in a defined order. Repository skills live in .agents/skills/<name>/SKILL.md, personal ones in ~/.agents/skills, admin ones in /etc/codex/skills, and system skills ship inside Codex. For the repository scope, Codex walks every directory from where you launched it up to the repository root, so a monorepo can put narrower skills in a 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. The awesome-codex-skills README says exactly that as of this update.

The evidence trail is public. In openai/codex issue 9752, filed on 23 January 2026 against version 0.89.0, project skills in .codex/skills stopped appearing in /skills. Issue 22869, filed in May 2026, treats ~/.agents/skills as the reference behaviour, and the October docs list only the .agents paths.

And yes, we got caught by our own advice. While checking this update we found that AITerm's Habits feature, which drafts skills for you (more on it below), still writes its Codex drafts to ~/.codex/skills. If a skill drafted there does not appear in /skills, move the folder to ~/.agents/skills.

Anatomy of a SKILL.md file

The file opens with YAML frontmatter between two lines of three dashes, carrying a name and a description. Those are the only required fields. Everything after the closing dashes is markdown that Codex reads once it has selected the skill, and the shortest useful skill is about fifteen lines.

Here is the one we would write for the AITerm repository, built straight from the rules in our own CLAUDE.md. Its reason to exist: an agent that runs swift build directly skips the signing step our 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. The description is the only thing Codex sees before it decides.

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

Control when a skill fires

With two switches, one per skill and one global. An agents/openai.yaml file inside the skill folder can set policy.allow_implicit_invocation: false, which keeps the skill out of automatic matching while $skill-name still works. A [[skills.config]] entry in ~/.codex/config.toml with enabled = false turns a skill off without deleting it.

# .agents/skills/deploy-prod/agents/openai.yaml
interface:
  display_name: "Deploy to production"
  short_description: "Ship main to prod, only when asked"
policy:
  allow_implicit_invocation: false   # $deploy-prod still works

# ~/.codex/config.toml
[[skills.config]]
path = "/Users/you/.agents/skills/old-release/SKILL.md"
enabled = false                      # kept on disk, invisible to Codex

The same file carries presentation fields (display_name, short_description, icons, a brand colour, a default prompt) and a dependencies.tools block for declaring MCP servers the skill needs. Restart Codex after any change to either file.

Skills became plugins, and plugins reached ChatGPT

If a tutorial sends you to github.com/openai/skills, you land on a deprecation notice pointing at the OpenAI plugins repository. The deprecation pull request went up on 16 June 2026. The .curated folder still works with skill-installer, but the .experimental folder that older guides reference now returns a 404.

Plugins wrap the same idea in a manifest. Each one sits at plugins/<name>/ with a .codex-plugin/plugin.json, and skills/ is one optional surface next to .mcp.json, commands/, agents/ and hooks.json. A plugin holding a single skill is a valid shape.

Here's what changed since our August version: the docs moved from developers.openai.com to learn.chatgpt.com, and plugins now live in a directory shared by ChatGPT and Codex. Standalone skills run in the ChatGPT desktop app, the CLI and the IDE extension. Skills bundled in a plugin also run in ChatGPT on web, desktop and mobile, where you call them with @ instead of $.

Turns out the format stabilised faster than the distribution did. A correction while we are here: our first version said the plugins repo carried a read-only banner. As of October 16, 2026 it does not, and it has taken more than 300 commits.

The nine skills worth installing first

The selection criterion was blunt: does it change what the agent does, or does it just rephrase what you would have typed anyway. Three ship with Codex, four come from OpenAI's curated catalog, two from the community.

Honestly, the right number of installed skills is smaller than any list suggests, this one included. Each one still costs description budget at every session start, used or not.

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

The honest caveat on all nine: a skill is instructions, not capability. None of these make the model better at Swift. They 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?

Four routes, depending on where the skill comes from: the curated catalog, a plugin marketplace, any public GitHub repository, or your own head. Every route ends as a folder on disk, and every route needs a fresh session afterwards, since discovery runs at session start.

# 1. From inside Codex, the curated catalog
$skill-installer gh-address-comments
$skill-installer linear

# 2. A plugin marketplace, for whole collections
codex plugin marketplace add owner/repo
codex plugin marketplace list
codex plugin marketplace upgrade

# 3. From your shell, any public repo with a SKILL.md
npx skills add owner/repo --skill skill-name -a codex -a claude-code

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

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

So, route two is the one OpenAI pushes now. A marketplace is a repo with a marketplace.json that lists plugins, and add accepts --ref and --sparse when you want a branch or a subfolder. Installed plugins land in a versioned cache under ~/.codex/plugins/cache/.

Route three is the cross-client one. The vercel-labs/skills CLI installs one package into Codex, Claude Code, Cursor, OpenCode, Gemini CLI and a dozen other clients. If you run more than one agent, it saves you maintaining two copies of the same instructions.

Do Claude Code skills work in Codex?

Mostly, because both follow the open Agent Skills format. A SKILL.md with a name, a description and plain instructions moves between them unchanged. What breaks is everything around it: folders, invocation, and the extra frontmatter keys Claude Code accepts and Codex ignores.

In practice, keep shared skills to name and description, and put client-specific behaviour in each client's own config. A skill that shells out to a specific binary or assumes a sandbox policy is the one that needs edits.

Writing your own against a 2 percent budget

Every skill you install costs context before it does anything. By default Codex spends at most 2% of the context window on the skill list, or 8,000 characters when the window is unknown. Past that, it shortens descriptions first, then drops skills with an "Exceeded skills context budget" warning.

The news since August: the budget is no longer hardcoded. openai/codex issue 19679 asked for it in April 2026, and the docs now document skills.max_context_tokens in config.toml, up to 10,000 tokens.

You're probably thinking the fix is now to crank the setting to 10,000 and move on. You can. Every token you hand the skill list is a token your actual task does not get, on every turn of every session, so the discipline stays the same: short descriptions, not fewer skills. Write the trigger, not the title.

# Bad: describes the skill to a human (200 characters)
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 (130 characters)
description: Build and sign the macOS app. Use when compiling, running
  or packaging after a Swift change. Not for the website in site/.

# Only if you have measured that you need it
# ~/.codex/config.toml
[skills]
max_context_tokens = 6000

The good version is 70 characters shorter and names a negative case, which keeps it from competing with other build-adjacent skills. Multiply that by twenty skills and you have headroom you did not have. Turns out that constraint improves matching as much as it saves usage.

Fair question: how many Codex skills is too many? Run /skills in a fresh session and check that everything you installed appears. If something is missing, you are over budget, and the fix is the prose before the setting.

Why does a skill not show up?

Four causes account for nearly all of it, and they are all silent: wrong directory, a UTF-8 byte order mark, a session you never restarted, or the budget. 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. Not yet. A badly described skill still appears in /skills, and a misfiled one does not, so the description is the last thing to suspect.

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

One cause is gone. Our August version told you symlinked skill folders do not load, per openai/codex issue 11314. The October docs state that symlinked skill folders are followed, so a dotfiles setup now works on a current Codex. Update before you debug.

# the checks, in the order that finds it fastest
ls -la .agents/skills/ ~/.agents/skills/          # right folder?
head -c 3 .agents/skills/*/SKILL.md | xxd | head -1   # efbbbf means BOM
head -1 .agents/skills/*/SKILL.md                 # must be exactly ---
codex --version                                   # old builds ignore symlinks
# then quit Codex and start a new session. Discovery runs once, at start.

If everything passes and the skill still hides, you are in budget territory. Trim the longest descriptions and check /skills again. If it appears but never fires on its own, invoke it with $skill-name while you rewrite the description.

Skills change what you have to supervise

This is the part most guides skip. Four of the nine skills above trigger a build, a test suite or a network round trip, so a session that used to answer in seconds now holds a pane for as long as your CI takes. 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 need to see which one is done.

The newer piece is Habits. AITerm reads the prompts you typed across your Claude Code, Codex and Gemini transcripts, groups requests of the same shape, and keeps only the ones that recur across several sessions. One click asks your own CLI to draft the SKILL.md, which you review (name, description, instructions, scope) before anything is written.

Measured on 309 transcripts totalling 1.1 GB, the first scan took 11 seconds in a debug build and later scans took 10 ms, because transcripts are append-only and only new bytes get read. 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.

Scope your triggers narrowly. A skill that runs the full test suite on a one-line string change is correct and useless, because you will stop invoking it.

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

Going further

Sources

1. Build skills, OpenAI documentation, checked October 16, 2026 (formerly developers.openai.com/codex/skills): scopes and paths, symlinks followed, agents/openai.yaml and allow_implicit_invocation, the 2% / 8,000-character budget, skills.max_context_tokens up to 10,000 tokens, [[skills.config]], plugins shared with ChatGPT.
2. Build plugins, OpenAI Codex documentation: codex plugin marketplace add, list, upgrade and remove, the skills manifest field, and the ~/.codex/plugins/cache/ install path.
3. openai/skills, Skills Catalog for Codex: the deprecation notice pointing at the plugins repository, the .curated folder (gh-address-comments, gh-fix-ci, playwright, sentry, linear among 39 skills) and the skill-installer syntax. Deprecation pull request opened 16 June 2026.
4. openai/plugins: the plugins/<name>/.codex-plugin/plugin.json manifest, the optional skills/ surface, and .agents/plugins/marketplace.json. No archive banner as of October 16, 2026.
5. Make skills metadata context budget configurable instead of hardcoded 2%, openai/codex issue 19679, opened 26 April 2026: the original SKILL_METADATA_CONTEXT_WINDOW_PERCENT = 2 and DEFAULT_SKILL_METADATA_CHAR_BUDGET = 8_000 constants and the truncation warning.
6. 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.
7. 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.
8. Codex CLI doesn't load skills from .agents/skills when it is a symlink, openai/codex issue 11314: the older symlink behaviour, superseded by the current docs.
9. Eval-fixture SKILL.md files load as real skills under Codex, melodic-software/claude-code-plugins issue 6741, opened 10 October 2026: Codex CLI 0.162.0 scanning plugin skills/ trees recursively.
10. awesome-codex-skills, Composio community: codebase-recon, codebase-migrate, webapp-testing, sentry-triage, create-plan, mcp-builder, changelog-generator, and the README still recommending $CODEX_HOME/skills.
11. vercel-labs/skills, the open agent skills tool: npx skills add owner/repo, the --skill and -a flags, and the supported clients.
12. Extend Claude with skills, Claude Code documentation: ~/.claude/skills and .claude/skills, /name invocation, disable-model-invocation, and the 1,536-character listing cap.
13. 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.