Codex skills: how to install and use them

Skills are how you teach Codex a repeatable workflow: a folder with a SKILL.md file (plus optional scripts and references) that Codex applies when a task matches, or when you invoke it by name. They are the highest-leverage customization Codex has, and they take minutes to start using.

The format

Every skill is a directory with a required SKILL.md whose frontmatter carries a name and a description. Optional subfolders extend it: scripts/ for executable code, references/ for documents the skill loads into context, assets/ for files used in output, and agents/ for UI metadata (openai.yaml).

---
name: code-reviewer
description: Review pull requests for correctness and style. Use when asked to review changes.
---

When reviewing a PR:
1. Read the diff fully before commenting.
...

The description doubles as the trigger: Codex matches your request against it for implicit invocation, so write it as a "use when" condition.

Installing skills

Skills live in ~/.codex/skills. The manual path:

mkdir -p ~/.codex/skills
# drop a skill folder in, e.g.:
unzip code-reviewer.zip -d ~/.codex/skills/

Codex picks up new skills automatically; if one does not appear, start a new session.

The built-in path: OpenAI maintains an official catalog at openai/skills on GitHub, and Codex ships a $skill-installer that installs curated skills by name:

$skill-installer install the create-plan skill

Curated skills come from the catalog's skills/.curated set, with experimental ones under .experimental.

Using skills

Three ways, in increasing explicitness:

Implicit: describe your task naturally; Codex applies a skill whose description matches.
Browse: run /skills to see what is installed and pick one.
Explicit: the $ prefix invokes a skill by name: $code-reviewer review the changes in this PR.

Explicit invocation is worth the habit when precision matters; implicit matching is great until two skills overlap.

Finding skills worth installing

Beyond the official catalog, the ecosystem is large and uneven. We index and verify skills continuously: browse skills for Codex in our directory, with provenance shown per listing. Because the SKILL.md shape is shared across agents, many skills written for Claude Code work in Codex too; the directory marks verified compatibility per agent, and our Claude Code skills guide covers the other side.

One caution that applies everywhere: a skill is instructions your agent follows with your permissions, and skill marketplaces across the agent ecosystem have had real problems with malicious packages. Read what a skill executes before installing it, prefer sources with provenance, and treat scripts/ folders with the same suspicion as any code you run.

Writing your own

Start with the workflow you keep re-explaining. Create the folder, write the description as a trigger condition, keep steps concrete, and test by phrasing the task naturally to confirm the skill fires. Once it works, consider contributing it back to the catalog or publishing it; reusable skills are quickly becoming the unit of agent expertise. To go deeper on Codex itself, see how to install Codex and what Codex costs to run.

Sources: Codex skills docs and openai/skills, checked June 2026.