Skip to content
Codex DesignBETA

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.md file: a name, a description, and instructions in Markdown. It can also hold scripts and reference files.
  • Install one by typing $skill-installer and the skill’s name or GitHub URL in Codex, or copy the folder into ~/.agents/skills. Restart Codex afterward.
  • Use one with /skills or 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/skills catalog is deprecated. New official skills ship inside plugins in the openai/plugins repository.

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

ScopePathUse it for
Repository.agents/skills in the current folder or above it, up to the repo rootSkills that belong to one project
User~/.agents/skillsSkills you want in every project
Organization/etc/codex/skillsSkills an admin installs for everyone
SystemBundled with Codexskill-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 /skills in 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:

Create a skill with $skill-creator
$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

SkillWhat it doesHow to get it
skill-creator, skill-installerCreate and install skillsBuilt in
imagegenGenerates images from a prompt inside CodexBuilt in
gh-fix-ciReads failing GitHub Actions logs and fixes the build$skill-installer gh-fix-ci
gh-address-commentsWorks through review comments on your open pull request$skill-installer gh-address-comments
playwrightDrives a real browser to test and screenshot what Codex built$skill-installer playwright
security-best-practicesReviews code for common security mistakes$skill-installer security-best-practices
Figma skillsTurn Figma frames into code and code into FigmaThe Figma plugin, via /plugins
Taste SkillPushes UI away from the generic AI lookSee the tutorial
pretty-uiChecks 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.md and sit directly inside the skill’s folder, under one of the paths above.
  • Check the frontmatter. Both name and description are 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_tokens in config.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.

Keep reading

An independent plugin for Codex. Not affiliated with or endorsed by OpenAI.