Codex skills: how to install, write and use them

Codex skills are folders with a SKILL.md file (a name, a description and instructions) that Codex loads when a task matches, plus optional scripts and reference files. You install curated ones with $skill-installer, write your own in .agents/skills in a repo or $HOME/.agents/skills for yourself, and call one by name with $ or let Codex pick it from its description.

Skills in Codex follow the open Agent Skills format, so most of what you write here also runs in other agents. For the format itself and how it compares across tools, see our guide to agent skills and how SKILL.md works. This guide sticks to Codex: where skills live, how they trigger, how to install and write them, and a short list worth trying. Setup details were checked against official OpenAI documentation on October 15, 2026.

What a skill is in Codex

OpenAI's Build skills page describes a skill as a directory with a required SKILL.md. The file's frontmatter needs name and description. Everything else is optional:

my-skill/
├── SKILL.md            # required: name, description, instructions
├── scripts/            # executable code
├── references/         # documentation Codex reads when needed
├── assets/             # templates and resources
└── agents/openai.yaml  # appearance and dependency metadata

my-skill/
├── SKILL.md            # required: name, description, instructions
├── scripts/            # executable code
├── references/         # documentation Codex reads when needed
├── assets/             # templates and resources
└── agents/openai.yaml  # appearance and dependency metadata

my-skill/
├── SKILL.md            # required: name, description, instructions
├── scripts/            # executable code
├── references/         # documentation Codex reads when needed
├── assets/             # templates and resources
└── agents/openai.yaml  # appearance and dependency metadata

The same skills work in ChatGPT and Codex. Codex does not read every skill in full at the start of a session. It first loads each skill's name, description and file path, and reads the full SKILL.md only once it picks that skill. OpenAI calls this progressive disclosure.

That initial list has a budget. By default it uses at most 2% of the model's context window, or 8,000 characters when the window size is unknown. You can change it with skills.max_context_tokens, up to 10,000 tokens. A large pile of installed skills costs context on every session even when none of them runs, which is one reason to keep descriptions short.

Where Codex loads skills from

Codex reads skills from these scopes, per OpenAI's docs:

A few details from the same page matter in practice:

• Codex picks up changes to skill files on its own. If an edit doesn't show up, restart Codex.

• It follows symlinked skill folders, so you can keep skills in one checkout and link them in.

• If two skills share a name, Codex doesn't merge them. Both can show up in the skill selector, so give repo skills distinct names.

Commit repo skills to .agents/skills and everyone who opens the repo in Codex gets them. Put personal habits in $HOME/.agents/skills.

How Codex picks a skill

There are two ways a skill runs.

Explicit: in the Codex CLI or the IDE extension, run /skills to browse what's loaded, or type $ followed by the skill name in your prompt, for example $skill-creator. In ChatGPT the equivalent is @.

Implicit: Codex chooses a skill on its own when your request matches the skill's description. The description decides whether that happens. OpenAI's advice is to keep it concise, with a clear scope and the trigger words a user would type. Say when the skill should trigger and when it should not.

Some skills should never run on their own, such as one that pushes code or opens a pull request. Add an agents/openai.yaml file with this to keep a skill explicit-only:

policy:
  allow_implicit_invocation: false

policy:
  allow_implicit_invocation: false

policy:
  allow_implicit_invocation: false

The skill still runs when you call it with $skill-name. The default is true.

To 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

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

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

How to install Codex skills

Curated skills with $skill-installer

Codex ships with a system skill called skill-installer. Ask for a curated skill by name:

$skill-installer gh-fix-ci

$skill-installer gh-fix-ci

$skill-installer gh-fix-ci

By default it installs from the curated folder of openai/skills. You can also hand it a GitHub folder URL for a skill in the repo's experimental folder or in another repo. The installer's own instructions say it can list what's available and install from other repos, private ones included. Codex detects newly installed skills automatically; restart it if the skill does not appear.

Use the installer for local setup and experiments. For sharing reusable skills with a team, OpenAI recommends packaging them as plugins.

Install a skill folder manually

Copy a trusted skill's complete folder into .agents/skills/ in your repository to share it with the team, or ~/.agents/skills/ for personal use. Keep the directory name consistent with the name in its frontmatter:

.agents/skills/release-notes/SKILL.md

.agents/skills/release-notes/SKILL.md

.agents/skills/release-notes/SKILL.md

Keep bundled scripts, references and assets beside the manifest. Check that the skill appears in /skills, invoke it with $release-notes, and confirm any required tools are installed before relying on it.

Skills inside plugins

A Codex plugin bundles skills with other pieces, such as MCP servers and hooks. In the Codex CLI, type /plugins to open the plugin browser, which groups plugins by marketplace and lets you install or uninstall them. Start a new session after installing before you use a plugin's skills.

You can add other marketplaces from the command line:

codex plugin marketplace add owner/repo
codex plugin marketplace list

codex plugin marketplace add owner/repo
codex plugin marketplace list

codex plugin marketplace add owner/repo
codex plugin marketplace list

A plugin can be nothing more than a wrapper around skills. OpenAI's plugin guide starts with a minimal plugin that packages one skill under a root skills/ folder, and Codex has a built-in $plugin-creator skill that scaffolds one.

Skills from other repos

Many skill repos on GitHub are written for several agents at once. Read a skill's SKILL.md, license and any scripts before installing it: a skill provides instructions your agent follows and code it may run on your machine. Pick skills for tasks you repeat, and check their required tools and expected output before adding more.

How to write a Codex skill

Start with $skill-creator

The fastest route is the built-in skill:

$skill-creator

$skill-creator

$skill-creator

It asks what the skill should do and when it should trigger, then drafts the folder. Instruction-only skills are the default. Its own SKILL.md gives the main rule for writing one: Codex is already capable, so only add context it doesn't already have.

Or write SKILL.md by hand

Create a folder whose name matches the skill's name, then add SKILL.md:

---
name: release-notes
description: Draft release notes from merged PRs since the last git tag. Use when the user asks for release notes, a changelog entry or a summary of what shipped. Do not use for commit messages.
---

1. Find the latest tag with `git describe --tags --abbrev=0`.
2. List merged PRs since that tag with `gh pr list --state merged --search "merged:>=<tag date>"`.
3. Group changes under Features, Fixes and Internal.
4. Output Markdown. Do not edit any files

---
name: release-notes
description: Draft release notes from merged PRs since the last git tag. Use when the user asks for release notes, a changelog entry or a summary of what shipped. Do not use for commit messages.
---

1. Find the latest tag with `git describe --tags --abbrev=0`.
2. List merged PRs since that tag with `gh pr list --state merged --search "merged:>=<tag date>"`.
3. Group changes under Features, Fixes and Internal.
4. Output Markdown. Do not edit any files

---
name: release-notes
description: Draft release notes from merged PRs since the last git tag. Use when the user asks for release notes, a changelog entry or a summary of what shipped. Do not use for commit messages.
---

1. Find the latest tag with `git describe --tags --abbrev=0`.
2. List merged PRs since that tag with `gh pr list --state merged --search "merged:>=<tag date>"`.
3. Group changes under Features, Fixes and Internal.
4. Output Markdown. Do not edit any files

The Agent Skills specification sets the rules both Codex and other agents expect:

The spec also recommends keeping SKILL.md under 500 lines and moving detail into references/ files that the agent loads only when needed.

Optional: agents/openai.yaml

This file is specific to OpenAI's products. Besides policy.allow_implicit_invocation, it supports an interface block (display name, short description, icons, brand color and a default prompt, shown in the ChatGPT desktop app) and dependencies.tools, where a skill can declare that it needs a tool such as an MCP server:

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

Other agents ignore this file, so it doesn't hurt portability.

Tips from OpenAI's guide

• Keep each skill to one job.

• Prefer instructions over scripts unless you need deterministic behavior or an external tool.

• Write steps in the imperative, with clear inputs and outputs.

• Test a few prompts against the description to check the skill triggers when it should, and stays quiet when it shouldn't.

Best Codex skills for engineers

All of these exist today in the repos named, and the descriptions come from each skill's own SKILL.md or README.

A review skill before you push

After a skill changes code, inspect the diff and run the relevant checks before committing. Our guide to reviewing AI-generated code covers the failure patterns to check. Bug Bench's Codex page tracks bugs in AI-attributed code reviewed by cubic; its observational results reflect both model choice and the work teams assign to each model.

Our product, cubic, publishes skills that run a review inside your agent. To install them for Codex:

npx @cubic-plugin/cubic-plugin install --to codex --skills-only

npx @cubic-plugin/cubic-plugin install --to codex --skills-only

npx @cubic-plugin/cubic-plugin install --to codex --skills-only

According to the skills docs, run-review reviews uncommitted changes or the current branch through its CLI, check-pr-comments handles unresolved PR review feedback, and cubic-loop repeats review and fixes up to an iteration limit. In Codex you call them by name or describe the task. For other options, see our post on a code review skill for Claude Code, Codex and Cursor.

Use the same skills in Claude Code and Cursor

Because Codex skills follow the Agent Skills format, the same folder usually works elsewhere. The difference is where each agent looks:

Cursor's docs say it reads .agents/skills and, for compatibility, also .codex/skills and .claude/skills, so a skill committed for Codex shows up in Cursor without changes. Claude Code's docs list .claude/skills and don't mention .agents/skills, so for Claude Code you copy or symlink the folder there. Claude Code's docs also note that outside Claude Code only the standard frontmatter fields work, so stick to name, description and the other spec fields if you want one skill for every agent. The Cursor skills guide covers Cursor's side, including its own invocation options.

A skill defines a reusable review procedure; Codex also has built-in review commands. Our Codex code review guide explains the local and GitHub review options so you can choose where each check belongs. For setting up Codex itself, start with our Codex CLI guide.

FAQ

Where are Codex skills stored?

OpenAI's docs list .agents/skills in the repo (including the current folder, a parent folder inside a Git repo and the repo root), $HOME/.agents/skills for personal skills, /etc/codex/skills for admin skills, and system skills bundled with Codex. Codex follows symlinks in these folders, so one shared checkout can feed several repos.

Why isn't Codex using my skill?

Codex chooses skills implicitly by matching your request against each skill's description, so a vague description is the usual cause. Rewrite it to name the task and the words a user would type, then test with a few prompts. You can also call it directly with $skill-name, check that it appears under /skills, and restart Codex if a recent edit hasn't loaded.

What's the difference between skills and plugins in Codex?

A skill is one folder of instructions and optional scripts. A plugin is a package for distribution that can hold several skills plus MCP servers, browser extensions and hooks, installed through /plugins or a marketplace. OpenAI recommends $skill-installer and local folders for your own setup and experiments, and plugins for sharing skills with others.

Are openai/skills and "awesome Codex skills" lists the same thing?

No. openai/skills is OpenAI's own catalog, with system skills bundled into Codex and curated skills you install with $skill-installer. "Awesome" lists are community collections on GitHub that link to skills from many authors, so check each one's SKILL.md and scripts before installing.

Can I use Claude skills in Codex?

Usually, yes. Both follow the Agent Skills format, so a folder with a valid SKILL.md can move from .claude/skills to .agents/skills. Fields specific to Claude Code won't do anything in Codex, and the curated migrate-to-codex skill exists to move skills, instruction files and MCP config from other tools into Codex.