Codex Skills
Codex skills are folders of instructions that OpenAI's coding agent loads when a request matches what the folder is for. Each folder holds a SKILL.md file and, optionally, the scripts, reference documents, and templates the task needs. OpenAI's documentation calls skills the authoring format for reusable workflows, and plugins the way to distribute them.
The format is not specific to Codex. It is the Agent Skills standard, originally developed by Anthropic and released as an open standard, and the client showcase at agentskills.io lists ChatGPT and Codex among the products that read the same SKILL.md file.
This page covers what Codex actually reads, the exact directories it scans, what carries over from a Claude skill and what does not, how to add a skill in a few minutes, twelve skills to install grouped by the job they help with, what a team has to decide once more than one person depends on the same skill, and the parts OpenAI has not documented.
A Codex skill is a directory containing a SKILL.md file: YAML frontmatter with a name and a description, then Markdown instructions. Codex lists the name, description, and file path at startup, and reads the full file when it picks the skill.
That loading order is the point of the format. OpenAI calls it progressive disclosure: ChatGPT and Codex start from each skill's name and description, then load the full SKILL.md instructions when they decide to use that skill. Bundled scripts, references, and assets are read only when the instructions call for them, so a folder of installed skills costs very little context until one of them is relevant.
Codex can reach a skill in two ways. You can invoke it explicitly, with /skills or by typing $ and mentioning the skill in Codex CLI and the IDE extension, or in ChatGPT by typing @. Codex can also pick a skill implicitly when your task matches the skill description, which is why the description has to say both what the skill does and when it should trigger, in the words someone would actually type.
01 / Locations
Codex reads skills from repository, user, admin, and system locations. The repository scope is the one that surprises people coming from another agent: Codex scans a directory named .agents/skills in every directory from your current working directory up to the repository root.
| Scope | Location | What it is for |
|---|---|---|
| Repo | $CWD/.agents/skills | The directory you launched Codex from. Skills that belong to one module or one service, checked in next to the code they describe. |
| Repo | $CWD/../.agents/skills | A folder above the working directory when you launch Codex inside a Git repository, for skills shared by a group of nested folders. |
| Repo | $REPO_ROOT/.agents/skills | The topmost folder of the Git repository. Root skills are available to any subfolder, which is where a team usually puts the ones everyone needs. |
| User | $HOME/.agents/skills | Personal skills that apply to every repository you work in, whether or not your teammates have them. |
| Admin | /etc/codex/skills | A shared system location on the machine or container, for SDK scripts, automation, and defaults an administrator wants every user on that machine to have. |
| System | Bundled with Codex | Skills OpenAI ships with the product, such as the skill creator and the plan skills. Available to everyone when they start Codex. |
Names are not merged across locations. OpenAI documents that if two skills share the same name, Codex does not merge them and both can appear in skill selectors. That is a real difference from the precedence rules other agents apply, and it means a personal skill and a repository skill with the same name coexist rather than one silently winning.
Symlinked skill folders work. Codex follows the symlink target when it scans these locations, which is how one checked-out copy of a skill can serve several repositories without being duplicated in each of them.
The initial list is budgeted. In Codex the startup list includes each skill's name, description, and file path, and it is capped at 2% of the model's context window, or 8,000 characters when the context window is unknown. If many skills are installed, Codex shortens descriptions first, and for large skill sets it may leave some skills out of the initial list and show a warning. The budget applies only to that list: once Codex selects a skill, it still reads the full SKILL.md.
You can turn a skill off without deleting it. A [[skills.config]] entry in ~/.codex/config.toml takes the path to the skill folder containing SKILL.md and an enabled flag, and the config reference documents both keys. Restart Codex after changing the file.
Codex detects skill changes automatically, and OpenAI's instruction when an update does not show up is to restart Codex. The same applies to skills you have just installed.
Skills are not the only file Codex reads. It also builds an AGENTS.md chain before doing any work, and the two formats answer different questions, which is the subject of AGENTS.md vs SKILL.md: two formats, two different jobs.
02 / Portability
The file transfers. The setup around it does not. Both products implement the same Agent Skills standard, so a SKILL.md written for one is usually readable by the other, but the directories, the invocation syntax, and every field beyond the standard are product-specific.
| Area | Codex | Claude Code | What that means |
|---|---|---|---|
| Skill file | SKILL.md with name and description in the frontmatter | SKILL.md with name and description in the frontmatter | The same file. Both products document the Agent Skills standard as the format they read. |
| Repository location | .agents/skills, scanned from the working directory up to the repository root | .claude/skills, at the project root and in nested directories | A repository that serves both agents carries both directories, or one of them is a symlink to the other. Both products document following symlinks. |
| Personal location | $HOME/.agents/skills | ~/.claude/skills | Two folders per teammate, kept current by hand. |
| Explicit invocation | /skills, or $ and the skill name | / and the skill name | Instructions that tell a reader to type a slash command are agent-specific. Skill bodies that name their own invocation syntax need editing per agent. |
| Implicit invocation | On by default, and can be turned off per skill with allow_implicit_invocation in agents/openai.yaml | Controlled by Claude Code frontmatter fields | The switch exists on both sides but lives in a different file, so the setting does not travel with the skill. |
| Extra fields | agents/openai.yaml for display metadata, invocation policy, and tool dependencies | Claude Code frontmatter such as invocation control, subagent execution, and dynamic context injection | Each product's extras are ignored or unknown outside it. The six fields in the Agent Skills specification are the portable set. |
| Distribution | Plugins, published to the plugin directory shared by ChatGPT and Codex, plus local and repository marketplaces | Plugins and plugin marketplaces | Two packaging systems with different manifests. A shared skill folder is portable; a packaged plugin is not. |
Stay inside the specification and the file travels. The Agent Skills specification defines six frontmatter fields: name and description are required, and license, compatibility, metadata, and allowed-tools are optional. Anthropic documents that Claude Code accepts extra fields of its own and that only the six spec fields work outside Claude Code. OpenAI's Codex documentation describes name and description and its own agents/openai.yaml file, and does not document what Codex does with the four optional spec fields.
Portability is about the format, not the result. The same instructions can load in both products and still produce different work, because the tools, the sandboxing, and the surrounding instructions differ. Test the skill in each agent your teammates actually run before you tell them it works there.
For the same walkthrough from the Claude side, including the frontmatter table and the surfaces skills run on, see Claude skills: what they are and how to use them.
03 / Install
There are three documented ways to end up with a skill Codex can use: write the folder yourself, install a curated one from inside Codex, or install a plugin that bundles skills. The manual path is the one worth learning first, because the other two produce the same thing.
A skill everyone working in the repository should have goes in .agents/skills at the repository root. A skill that only makes sense for one service goes in .agents/skills inside that service directory, because Codex scans every level from your working directory up to the root. A skill that is yours alone goes in $HOME/.agents/skills.
Make a directory named after the skill and put a SKILL.md file inside it. The frontmatter needs name and description. The specification requires the name to match the parent directory name, to be at most 64 characters, and to use lowercase letters, numbers, and single hyphens.
The description is what Codex matches your request against, and it is also the part that gets shortened when many skills are installed. OpenAI's guidance is to write concise descriptions with clear scope and boundaries, and to front-load the key use case and the trigger words so a host can still match the skill if descriptions are shortened.
The body is plain Markdown with no format restrictions. The specification recommends keeping SKILL.md under 500 lines and moving detailed reference material into separate files, because the whole body is read once the skill activates while referenced files load only when the instructions ask for them.
Run /skills in Codex CLI or the IDE extension and pick the skill, or type $ and mention it by name. Explicit invocation confirms Codex found the folder. After that, leave it to implicit matching and see whether your description actually triggers on the requests you expected.
An agents/openai.yaml file inside the skill folder can set the display name, short description, icons, brand color, and default prompt shown in the ChatGPT desktop app, declare tool dependencies such as an MCP server, and set allow_implicit_invocation to false so the skill runs only when you invoke it explicitly.
Inside Codex, $skill-creator drafts a skill by asking what it does, when it should trigger, and whether it needs scripts. Record and Replay captures a workflow you demonstrate and drafts a skill from it. $skill-installer followed by a curated skill name installs one of OpenAI's, and it also takes a GitHub folder URL for skills published elsewhere. It saves them to ~/.codex/skills (or $CODEX_HOME/skills), an older personal location that Codex still reads.
SKILL.md starting point
---
name: release-notes
description: Draft release notes from merged pull requests. Use when the user asks for release notes, a changelog entry, or a summary of what shipped.
---
## Steps
1. List the merged pull requests since the last tag.
2. Group them into features, fixes, and internal changes.
3. Write one line per user-visible change, in plain language.
4. Leave internal refactors out unless they change behavior.
## Output
A Markdown section titled with the version and date.04 / Skills to install
The skills below are ones Codex users install from public repositories, grouped by the job they help with. Each entry was checked at its source on September 25, 2026 against the same conditions: the SKILL.md is readable at the linked folder, the publisher is OpenAI, Anthropic, or Vercel or the repository is among the most installed on skills.sh, the skill changed within the past twelve months, and a license is stated (Apache 2.0 or MIT for every entry here). Codex already ships a few skills of its own, including $skill-creator and $skill-installer, so they are not listed.
Reads the logs of failing GitHub Actions checks on a pull request and drafts a fix plan, which it applies only after you approve it.
Requires: The GitHub CLI signed in with repo and workflow scopes. Checks from other CI providers are reported by link only.
Install gh-fix-ci
$skill-installer gh-fix-ciCollects the review comments on the open pull request for your current branch and fixes only the ones you pick from a numbered list.
Requires: The GitHub CLI signed in.
Install gh-address-comments
$skill-installer gh-address-commentsA set of skills for the whole development loop, including brainstorming, writing-plans, test-driven-development, and systematic-debugging, which Codex loads as the task moves from design to code. It is listed in OpenAI's official Codex plugin directory.
Requires: Codex CLI or the ChatGPT desktop app for the plugin route, since the IDE extension does not support plugins.
Install: In Codex CLI, run /plugins and search for superpowers, or open Plugins in the ChatGPT desktop app. To install only the skills from a terminal, use the command below.
Install Superpowers
npx skills add obra/superpowers -a codexSource: obra/superpowers
Questions you about a plan or design in numbered rounds, with a proposed answer for each question, until no decision in it is left open.
Install grilling
npx skills add mattpocock/skills --skill grilling -a codexGives Codex a design direction when it builds or reshapes a UI, with concrete rules on typography and layout meant to keep the result from looking generated.
Install frontend-design
npx skills add anthropics/skills --skill frontend-design -a codexReviews UI files against Vercel's Web Interface Guidelines, which cover accessibility and interaction details, and reports each finding as file:line.
Requires: Network access, because it downloads the current guidelines from GitHub before each review.
Install web-design-guidelines
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a codexSource: vercel-labs/agent-skills, skills/web-design-guidelines
70 React and Next.js performance rules from Vercel, ordered by impact, that Codex applies when it writes or reviews components and data fetching. A copy also ships in OpenAI's Build Web Apps plugin.
Install vercel-react-best-practices
npx skills add vercel-labs/agent-skills --skill vercel-react-best-practices -a codexSource: vercel-labs/agent-skills, skills/react-best-practices
Drives a real browser from the terminal with playwright-cli, so Codex can walk through a UI flow and capture snapshots while it debugs.
Requires: Node.js with npx.
Install playwright
$skill-installer playwrightTests a local web app by writing Python Playwright scripts, with a helper that starts your dev servers before the test and stops them after.
Requires: Python with the Playwright package and a browser installed.
Install webapp-testing
npx skills add anthropics/skills --skill webapp-testing -a codexLoads security guidance for the languages and frameworks in your project, to write secure-by-default code or produce a prioritized report when you ask for one.
Requires: A Python, JavaScript or TypeScript, or Go codebase. It triggers only when you ask for security guidance or a review.
Install security-best-practices
$skill-installer security-best-practicesSource: openai/skills, skills/.curated/security-best-practices
Handles PDF work where layout matters, generating files with reportlab and checking them by rendering each page to an image.
Requires: Poppler and the Python packages reportlab, pdfplumber, and pypdf.
Install pdf
$skill-installer pdfGuides the design and build of an MCP server in Python with FastMCP or in TypeScript with the MCP SDK, from reading the target API to writing an evaluation set.
Requires: Nothing for the guide. Its optional evaluation script uses the Anthropic SDK and needs an Anthropic API key.
Install mcp-builder
npx skills add anthropics/skills --skill mcp-builder -a codexEvery skill in this list ends up as a folder with a SKILL.md in a place Codex scans, and there are three ways to get it there. Inside Codex, $skill-installer followed by a name installs from OpenAI's curated set, and it also accepts a GitHub folder URL for skills published elsewhere, for example $skill-installer install https://github.com/anthropics/skills/tree/main/skills/frontend-design. It writes to ~/.codex/skills (or $CODEX_HOME/skills), an older personal location that Codex still reads alongside $HOME/.agents/skills.
From a terminal, npx skills add with -a codex puts the skill in .agents/skills of the current project, and adding -g installs it in ~/.codex/skills instead. You can also copy the folder from the source into .agents/skills at the repository root, or into $HOME/.agents/skills to have it in every repository you open. Codex picks up new skills automatically; restart it if one does not appear.
Superpowers is packaged as a plugin, so its documented route is /plugins in Codex CLI or the Plugins tab in the ChatGPT desktop app. OpenAI marks the openai/skills repository as deprecated in favor of openai/plugins, although the installer bundled with Codex still installs curated skills from it by name.
A team that settles on a few of these still has to keep track of which ones it uses and where each one came from, so the next teammate installs the same folder. Skills Board is the web app where a team keeps and shares its AI skills: every entry records the repository and path it came from, and a teammate can open the source, copy an install command, download a ZIP, or search the same list from a compatible agent over an authenticated MCP endpoint.
05 / Teams
Two problems hide behind one word. Distribution is getting the files onto each teammate's machine. Selection is knowing which skill to use for a task and why that one. Codex has answers for the first. The second is not a Codex problem at all.
If every skill your team uses lives in a repository everyone works in, the answer is short: commit them to .agents/skills at the repository root, and Codex picks them up with no extra tooling. That is the best available setup for a single-repository team, and no shared library improves on it. Nothing on this page should talk you out of it.
It stops being enough when the skills come from other people's repositories, when they are useful in more than one repository, or when teammates run different agents. Then distribution splits: OpenAI's answer is plugins, published to the plugin directory shared by ChatGPT and Codex, or a marketplace file checked into $REPO_ROOT/.agents/plugins/marketplace.json or kept personally at ~/.agents/plugins/marketplace.json and added with codex plugin marketplace add. Anthropic's answer is its own plugin system. Neither one carries the other's packaging.
The selection layer usually has no home at all. Which skill the team settled on, and why, ends up in a chat thread, a bookmark, or one person's memory. Skills Board is a web app for that layer: the smaller set of skills your team settled on, in one searchable place, with the original source visible on every entry, and no assumption about which agent a teammate runs.
The operational version of this, with one canonical source and a tested install path per agent, is in Manage skills across Claude Code, Codex, and Cursor.
06 / Limits
Some of what people expect to be documented is not. These are the gaps we found while checking OpenAI's current documentation, written out rather than guessed at.
The Agent Skills specification defines license, compatibility, metadata, and allowed-tools as optional fields, and marks allowed-tools experimental with support that varies between implementations. OpenAI's Codex skills documentation describes name and description and its own agents/openai.yaml file, and says nothing about what Codex does with the other four. Treat their behavior in Codex as unverified.
The documented locations are .agents/skills from the working directory up to the repository root, $HOME/.agents/skills, /etc/codex/skills, and the skills bundled with Codex. A directory used by another agent is not among them, so a repository that serves both agents needs both paths present, whether by copying the folder or by symlinking it.
OpenAI documents standalone skills as available in the ChatGPT desktop app, Codex CLI, and the IDE extension, and skills bundled in plugins as also available in Chat and Work across ChatGPT on the web, desktop, and mobile. Other Codex surfaces are not listed for standalone skills, so do not assume a folder on your laptop is present wherever else Codex runs.
The Codex skills documentation links openai/skills for examples, and the open-source page lists it as the home of reusable skills for ChatGPT and Codex. The repository itself opens with a notice marking it deprecated and pointing to the OpenAI plugins repository for current Codex skill and plugin examples. Both pages were checked on the date above.
The initial skill list is capped at 2% of the model's context window, or 8,000 characters when it is unknown, and Codex shortens descriptions and may omit skills beyond that, with a warning. The number of skills that fits depends on the model and on how long your descriptions are, so the practical limit is something you observe rather than look up.
07 / Questions
Editorial method: every claim about how Codex handles skills comes from the first-party documentation below, checked on the date at the top of this page. Where the documentation says nothing, this page says so instead of filling the gap. Product behavior changes, so check the linked pages before you rely on a detail.
The skill directory layout, progressive disclosure and the initial list budget, explicit and implicit invocation, the four location scopes, symlink support, duplicate names, the skill creator and installer, the [[skills.config]] switch, and agents/openai.yaml.
The skills.config array and its path and enabled keys, and the feature flag that lets Codex prompt to install missing MCP dependencies for a skill.
The six frontmatter fields and their constraints, the naming rules, the optional scripts, references, and assets directories, and the progressive disclosure and file-size recommendations.
The format as an open standard originally developed by Anthropic, and the showcase entry listing ChatGPT and Codex among the products that read it.
Where Claude Code loads skills from, slash-command invocation, symlinked skill folders, and which frontmatter fields work outside Claude Code.
The plugin manifest and skills directory, the plugin directory shared by ChatGPT and Codex, repository and personal marketplace files, and the codex plugin marketplace commands.
How Codex builds its instruction chain at startup, from the Codex home directory down to the working directory, and merges the files it finds.
Which parts of Codex are open source, including the CLI at openai/codex, and the repositories listed for skills and plugins.
The curated and system skill folders, the $skill-installer usage examples, per-skill licensing, and the notice marking the repository deprecated in favor of openai/plugins.
The SKILL.md of $skill-installer as it ships with Codex: the curated list it reads by default, installs from a GitHub folder URL, and the install location, $CODEX_HOME/skills, which defaults to ~/.codex/skills.
The source that keeps $CODEX_HOME/skills as a user skill location for backward compatibility, next to $HOME/.agents/skills.
The plugins in OpenAI's default Codex marketplace, including Superpowers and the Build Web Apps plugin that carries a copy of Vercel's React rules.
The /plugins browser in Codex CLI, the Plugins tab in the ChatGPT desktop app, and the note that plugins are not available in the IDE extension.
The npx skills add command with its --skill, --agent, and --global options, the codex agent id with its .agents/skills and ~/.codex/skills paths, and npx skills find.
The frontend-design, webapp-testing, and mcp-builder skills, each with an Apache 2.0 license file in its folder.
The web-design-guidelines and react-best-practices skills under the MIT license. The second one is named vercel-react-best-practices in its frontmatter.
The Superpowers skills, their MIT license, and the documented Codex install through /plugins and the Plugins tab.
The grilling skill under skills/productivity, and the repository's MIT license.
Install counts reported by the skills CLI, used to check which repositories are among the most installed. The counts cover every agent together and leave out $skill-installer and plugin installs.
Put your team’s skills somewhere everyone can find them.
Free forever, MIT licensed, and open source. Create a library, save the first skill, and invite the people who keep asking which one to use.