Codex skills.
A Codex skill is a folder with a SKILL.md file that teaches Codex one kind of work, like fixing CI or reviewing a design. This guide covers where skills live, how to install and call them, how to write one that Codex picks at the right time, and which ones to install first.
Updated November 12, 2026 · 7 min read
The short answer
- A skill is a folder with a
SKILL.mdfile: aname, adescription, and instructions in Markdown. It can also hold scripts and reference files. - Install one by typing
$skill-installerand the skill’s name or GitHub URL in Codex, or copy the folder into~/.agents/skills. Restart Codex afterward. - Use one with
/skillsor by typing$and its name. Codex also picks a skill on its own when your request matches its description. - Write one with the built-in
$skill-creator. The description decides when Codex uses it, so spend most of your time there. - OpenAI’s
openai/skillscatalog is deprecated. New official skills ship inside plugins in theopenai/pluginsrepository.
What a Codex skill is
A skill packages instructions, and optionally scripts and resources, for one task. Codex reads only each skill’s name and description at the start of a session. When a task matches a description, or you mention the skill, it loads the full SKILL.md. That is why you can keep dozens of skills installed without filling the context window.
Skills follow the open Agent Skills format, so the same folder usually works in other agents that read SKILL.md, including Claude Code. A plugin is a different thing: an installable bundle that can contain several skills plus MCP servers and hooks. See Codex plugins vs skills for the difference.
Where Codex skills live
| Scope | Path | Use it for |
|---|---|---|
| Repository | .agents/skills in the current folder or above it, up to the repo root | Skills that belong to one project |
| User | ~/.agents/skills | Skills you want in every project |
| Organization | /etc/codex/skills | Skills an admin installs for everyone |
| System | Bundled with Codex | skill-creator, skill-installer, and a few others |
Codex scans every .agents/skills folder from where you started it up to the repository root. Two skills with the same name are not merged; both show up in the list. Symlinked skill folders work, which is handy if you keep your skills in one Git repository.
How to use a skill
- Pick it: run
/skillsin the Codex CLI or IDE extension and choose one. - Mention it: type
$and the skill’s name in your prompt, for example$gh-fix-ci the build on this branch is red. - Let Codex choose: describe the task normally. If it matches a skill’s description, Codex loads that skill itself.
In the ChatGPT desktop app, type @ instead of $.
How to install Codex skills
With $skill-installer
$skill-installer is a system skill that ships with Codex. Give it a name or a GitHub folder:
$skill-installer gh-address-comments
$skill-installer install https://github.com/ummydev/pretty-ui/tree/main/skills/pretty-ui
A bare name installs from OpenAI’s curated catalog. A URL installs from any public repository. Restart Codex if the new skill does not appear.
By copying the folder
A skill is only files, so you can also clone or copy its folder into ~/.agents/skills (every project) or .agents/skills (one project). This is the easiest way to share a skill with your team: commit it to the repository and everyone who opens the project in Codex gets it.
From a plugin
OpenAI has deprecated the openai/skills repository and now ships its own skills inside plugins, in the openai/plugins repository: Figma, Notion, Linear, GitHub, Vercel, Build Web Apps, Product Design, and more. Run /plugins in the Codex CLI to browse and install them. A plugin installs its skills and any tools they need in one step.
How to write your own skill
The fastest start is to ask Codex:
$skill-creator Create a user-level skill called design-review. It checks a UI screen against DESIGN.md in the project: colors and fonts from the file only, an 8px spacing grid, body text 16px or larger, and no emoji used as icons. It reports problems as a list with the file and line, then fixes them.
Or write the file yourself, in ~/.agents/skills/design-review/SKILL.md:
---
name: design-review
description: Review a UI screen against the project's DESIGN.md. Use when the user asks for a design review, says a screen looks off, or before finishing any UI change.
---
1. Read DESIGN.md. If there is none, say so and stop.
2. Check colors, fonts, spacing, and type sizes against it.
3. List each problem with the file and line, then fix it.
Three things make the difference between a skill Codex uses and one it ignores:
- Write the description for matching. Say what the skill does and when to use it, in the words people actually type. “Use when the user asks for a design review” works; “Design helper” does not.
- Keep SKILL.md short. Put long references in a
references/folder and tell the skill when to read them. Codex loads the extra files only when needed. - Use scripts for exact steps. If something must happen the same way every time, such as a check or a conversion, put it in
scripts/and have the skill run it.
To stop Codex from using a skill on its own while keeping $name working, add agents/openai.yaml to the skill folder with policy: { allow_implicit_invocation: false }.
Codex skills worth installing
| Skill | What it does | How to get it |
|---|---|---|
skill-creator, skill-installer | Create and install skills | Built in |
imagegen | Generates images from a prompt inside Codex | Built in |
gh-fix-ci | Reads failing GitHub Actions logs and fixes the build | $skill-installer gh-fix-ci |
gh-address-comments | Works through review comments on your open pull request | $skill-installer gh-address-comments |
playwright | Drives a real browser to test and screenshot what Codex built | $skill-installer playwright |
security-best-practices | Reviews code for common security mistakes | $skill-installer security-best-practices |
| Figma skills | Turn Figma frames into code and code into Figma | The Figma plugin, via /plugins |
| Taste Skill | Pushes UI away from the generic AI look | See the tutorial |
| pretty-ui | Checks UI for AI design tells and fixes them | $skill-installer install https://github.com/ummydev/pretty-ui/tree/main/skills/pretty-ui |
Each of these, and more than 20 others, has its own page in our Codex skills directory, with the install command and a prompt to try.
For design work specifically, we compare the options in the best Codex skills for UI design and Taste Skill vs Impeccable vs UI UX Pro Max.
Turn off a skill, or fix one that doesn’t show up
To turn off a skill without deleting it, add this to ~/.codex/config.toml and restart Codex:
[[skills.config]]
path = "/Users/you/.agents/skills/design-review/SKILL.md"
enabled = false
Use name = "design-review" instead of path to turn off every skill with that name.
If a skill is missing from /skills:
- Restart Codex. New skills load when a session starts.
- Check the folder. The file must be named
SKILL.mdand sit directly inside the skill’s folder, under one of the paths above. - Check the frontmatter. Both
nameanddescriptionare required. - You may have too many. The starting list of skills gets about 2% of the context window. Past that, Codex shortens descriptions and can leave skills out, with a warning. Raise the budget with
skills.max_context_tokensinconfig.toml, or remove skills you don’t use.
Frequently asked questions
Do Claude Code skills work in Codex?
Usually, yes. Both use the SKILL.md format. Copy the folder from ~/.claude/skills into ~/.agents/skills. A skill that tells the agent to use a tool only one of them has will need editing.
What is the difference between a skill and AGENTS.md?
AGENTS.md is loaded in every session in that project, so it suits rules that always apply. A skill loads only when a task needs it, so it suits workflows you use sometimes, and it can carry scripts and reference files.
Where can I find more Codex skills?
OpenAI’s plugins in /plugins, the deprecated but still readable openai/skills repository, and skills that authors publish on GitHub. Read a skill’s files before you install it, especially its scripts: a skill runs with the same access Codex has.