Skills / Guides

Codex skills

Skills give OpenAI Codex a reliable way to do a specific job. Here is where Codex finds them, how to start one, how to install and write your own, and how to switch one off.

What a Codex skill is

A skill is a folder containing a SKILL.md file with a name, a description and instructions, plus optional scripts/, references/ and assets/ folders. Codex skills follow the open Agent Skills standard, the same format Claude Code uses, and work in the Codex CLI, the IDE extension and the ChatGPT desktop app.

Codex starts each session with a short list of every skill's name, description and file path, and reads the full SKILL.md only when it decides to use one. That list is capped at 2% of the model's context window (8,000 characters if the window is unknown). With many skills installed, Codex shortens descriptions first and may drop some from the list. You can raise the budget to as much as 10,000 tokens with the skills.max_context_tokens setting.

How to start a skill

Explicitly: run /skills, or type $ and the skill name, for example $skill-creator.
Automatically: Codex picks a skill when your request matches its description. Put the main use case and trigger words at the start of the description so it still matches when Codex shortens it.

Where Codex looks for skills

Scope	Folder	Good for
Repository	`.agents/skills` in the current folder, each parent folder, and the repo root	Team skills checked into the project, including ones for a single module
User	`~/.agents/skills`	Your own skills, in every repository
Admin	`/etc/codex/skills`	Defaults for every user on a machine or container
System	Bundled with Codex	Built-ins such as skill-creator and plan

Codex follows symlinked skill folders. If two skills share a name, Codex does not merge them; both can appear in the selector.

How to install skills in Codex

Curated skills: $skill-installer

For skills from OpenAI's curated list, ask the built-in installer, for example:

$skill-installer linear

Plugins from a marketplace

Many skill packs are published as Codex plugins. Add the repository as a marketplace, then add the plugin:

codex plugin marketplace add mattpocock/skills
codex plugin add mattpocock-skills@mattpocock

Some plugins, like Superpowers, are in the official Codex plugin directory: run /plugins in the CLI, search, and choose Install Plugin.

By hand

Copy a skill folder into ~/.agents/skills/ or your repository's .agents/skills/. Codex picks up new skills automatically; restart it if one does not appear.

How to write your own Codex skill

Type $skill-creator. It asks what the skill should do, when it should trigger, and whether it needs scripts. Instruction-only is the default.
Or show instead of tell: Codex's Record & Replay feature records a workflow and drafts a skill from it.
Or write it yourself. Use the SKILL.md generator, then save it as ~/.agents/skills/<name>/SKILL.md.

OpenAI's advice for good skills: one job per skill, instructions before scripts, imperative steps with clear inputs and outputs, and test prompts that check the description triggers when it should.

Turn a skill off without deleting it

Add an entry to ~/.codex/config.toml and restart Codex:

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Optional: agents/openai.yaml

A skill can include agents/openai.yaml to set its display name, icon and colour in the ChatGPT desktop app, declare tool dependencies such as an MCP server, and stop Codex from starting it automatically:

interface:
  display_name: "Weekly status"
  short_description: "Turn notes into a status email"
policy:
  allow_implicit_invocation: false

With allow_implicit_invocation: false, the skill only runs when you mention it with $.

Popular skills with Codex install instructions

grill-me: A relentless interview that turns a loose idea into decisions you can defend.
UI UX Pro Max: A searchable design library your agent consults before it writes any UI.
Everything Claude Code (ECC): A full engineering system for your agent: plan, test, review, verify, remember.
Superpowers: Makes your agent ask what you want, plan it, test first, and review its own work.
Impeccable: A design vocabulary for your agent: polish, audit, critique, bolder, quieter.
Taste Skill: Gives coding agents an art direction, real pictures, and a browser to check their work.

FAQ

Can I use Claude skills in Codex?

Usually yes. Both follow the open Agent Skills standard. Copy the skill folder into ~/.agents/skills or your repository's .agents/skills. Codex ignores frontmatter fields that only Claude Code understands, such as disable-model-invocation.

Where does Codex store skills?

Codex reads .agents/skills in your current folder and every parent folder up to the repository root, your personal ~/.agents/skills, /etc/codex/skills for admin skills, and the skills bundled with Codex.

How do I see which skills Codex has loaded?

Run /skills in the Codex CLI or IDE extension, or type $ to get a list of skills you can mention. In the ChatGPT desktop app, open Skills in the sidebar.

What is the difference between a skill and a plugin in Codex?

A skill is the workflow itself: a folder with SKILL.md. A plugin packages one or more skills, optionally with MCP connections, so other people can install them in one step.

Based on OpenAI's Codex skills documentation (developers.openai.com/codex/skills), checked on 2026-10-16. New to skills? Start with what skills are.