The short answer
- 1For every repository, the Skill’s folder goes in
~/.agents/skills/; for one repository only, in that repo’s.agents/skills/. - 2
SKILL.mdmust carry aname(64 characters at most) and adescription(1,024 at most), or Codex won’t accept it. - 3Type
$and the name to start it, or/skillsto choose from a list. - 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.
- 1
On the Skill’s The Frontier Brief page, choose Copy install prompt, then Copy in the dialog.
- 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
Approve the device code your browser shows.
- 1
Sign in the first time. Your browser opens and asks you to approve a device code.
Terminal npx --yes fable5-cli@latest login - 2
Run the install. Leave the flag off: the CLI’s default folder is already the one Codex reads.
Terminal npx --yes fable5-cli@latest install <slug>
On the Skill’s page, choose Download ZIP, or use a Skill folder from elsewhere. Look through SKILL.md and scripts/ first, since the agent acts on those instructions and may run those scripts. Then move the folder across whole:
mkdir -p ~/.agents/skills
mv ~/Downloads/my-skill ~/.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:
$launch-page Tidewell, a booking site for a small surf schoolAfter 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.
| Scope | Folder |
|---|---|
| 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/ |
| System | Shipped 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.
Pulled in on demand
- A folder under
.agents/skills/ - Used when a task fits, or when you type
$name - Repeatable work with several steps
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.
| Symptom | What to do |
|---|---|
Absent from /skills | Put it at ~/.agents/skills/<name>/, checking for an extra ZIP level |
| Shown with no description | Add both name and description to the frontmatter |
| A project Skill is missing | Launch Codex from inside the repository |
ChatGPT desktop app: $ lists nothing | Known 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?
