Black Friday: Lock in your founding rate.Compare plans

Every Premium Skill for $19.9/month. Cancel anytime. See plans

Skip to content

Codex Skills: install and run Agent Skills in OpenAI Codex

Codex loads Skills from ~/.agents/skills/, still honours the older ~/.codex/skills/, and starts one when you type $ and its name. Below: installing, confirming it loaded, and Skill versus AGENTS.md.

For
People who use Codex
Time
About 8 minutes

The short answer

  1. 1For every repository, the Skill’s folder goes in ~/.agents/skills/; for one repository only, in that repo’s .agents/skills/.
  2. 2SKILL.md must carry a name (64 characters at most) and a description (1,024 at most), or Codex won’t accept it.
  3. 3Type $ and the name to start it, or /skills to choose from a list.
  4. 4Want something finished? Browse Codex Skills, each a single command away.

What you need first

Skills run in three Codex apps: the desktop app (Codex in the ChatGPT desktop app), the terminal (Codex CLI) and your editor (Codex IDE extension). Installing with The Frontier Brief CLI also takes a Mac or Windows machine running Node.js 22+.

How to add a Skill to Codex

The Frontier Brief CLI and Codex share a default folder, ~/.agents/skills/, so no flag is needed. Pick any route.

Quickest when Codex is already running
  1. 1

    On the Skill’s The Frontier Brief page, choose Copy install prompt, then Copy in the dialog.

  2. 2

    Paste it into Codex and send. Codex fetches The Frontier Brief install steps and runs the right command for you.

    Install prompt
    Read https://fable5.app/skills/<slug>/install.md and follow the instructions to install the skill.
  3. 3

    Approve the device code your browser shows.

    You should see: Codex naming the version it put in and the path, somewhere under ~/.agents/skills/.

For OpenAI’s own catalog, Codex has $skill-installer. It writes to the older ~/.codex/skills/, which Codex still reads, so both installers’ Skills share one list.

Confirm Codex picked it up

Type /skills in the CLI or IDE extension, or start typing $ plus the name. The ChatGPT desktop app lists them under Skills in its sidebar. New Skills appear by themselves; restart Codex if one doesn’t.

Start a Skill in Codex

Type $, the name, then your request:

Codex CLI
$launch-page Tidewell, a booking site for a small surf school

After one good run, plain words are enough: Codex matches requests to descriptions. With lots of Skills it trims each description until the list uses roughly 2% of the context window, so lead with what the Skill is for.

The folders Codex reads

Five scopes feed Codex Skills; you will mostly use two, the repository’s and your own.

ScopeFolder
Repository.agents/skills/ in each folder between where you launch Codex and the repo root
Personal~/.agents/skills/
Personal (legacy)~/.codex/skills/: not in the docs, but Codex’s source code still reads it
Admin/etc/codex/skills/
SystemShipped inside Codex, for example $skill-creator and plan

Same-name Skills are not merged; both may appear in the picker, so remove or rename the unwanted copy.

Skills or AGENTS.md in Codex?

Codex reads AGENTS.md as each run starts, so it fits short rules that always hold. A Skill arrives only for a task that calls for it, so it fits longer procedures you repeat.

Skill

Pulled in on demand

  • A folder under .agents/skills/
  • Used when a task fits, or when you type $name
  • Repeatable work with several steps
AGENTS.md

Read as every run begins

  • Starts with ~/.codex/AGENTS.md, then each folder’s file on the way from the repo root to where you launched
  • Closer files override; 32 KiB in total by default
  • Brief rules such as how to test, style and limits

What works: about one screen of rules in AGENTS.md, every step-by-step procedure in a Skill. More in Skills vs instructions.

Skill missing in Codex? Find your symptom

A missing Skill has nearly always landed in the wrong place or gained an extra level when unzipped.

SymptomWhat to do
Absent from /skillsPut it at ~/.agents/skills/<name>/, checking for an extra ZIP level
Shown with no descriptionAdd both name and description to the frontmatter
A project Skill is missingLaunch Codex from inside the repository
ChatGPT desktop app: $ lists nothingKnown issue: openai/codex issue 28505. Try /skills or a restart; a copy in ~/.codex/skills/ may help (we have not tested it)

Common questions

Which folder holds Codex Skills?

Yours in ~/.agents/skills/, a repository’s in its .agents/skills/, an admin’s in /etc/codex/skills/. Codex also reads the older ~/.codex/skills/, where $skill-installer installs.

How do Codex Skills differ from AGENTS.md?

Codex reads AGENTS.md whenever a run starts. It loads a Skill only for a task that calls for it.

Can I use Codex Skills in ChatGPT?

Standalone Skills run in Codex’s CLI, its IDE extension and the ChatGPT desktop app. For ChatGPT on the web or a phone, ship the Skill inside a plugin.

How can I build my own Codex Skill?

Ask $skill-creator, a system Skill bundled with Codex.

Sources

Did this guide help?