By agent

Codex Skills: add and use Agent Skills in OpenAI Codex

Codex reads Skills from ~/.agents/skills/ and the older ~/.codex/skills/, and runs one when you type $ plus its name. Install from SkillsRadar, verify it loaded, and know when AGENTS.md is the better place.

For Codex users8 min to complete

Browse Codex Skills Compare agents

Start here:Install·Where it looks·Skills vs AGENTS.md

The short answer

1Put the Skill folder in ~/.agents/skills/ (or ~/.codex/skills/) for every repo, or in .agents/skills/ for one repository.
2Codex needs both name (≤64 chars) and description (≤1,024) in SKILL.md.
3Type $ plus the Skill’s name to run it, or /skills to pick from a list.
4Browse Codex Skills on SkillsRadar and install with npx @skillsradar/cli@latest install <slug> --agent codex.

Before you start

Skills work in the Codex CLI, the Codex IDE extension, and Codex in the ChatGPT desktop app. Standalone Skills do not reach ChatGPT on the web or mobile unless you ship them inside a plugin.

How to add Skills to Codex

SkillsRadar’s Codex adapter writes to ~/.codex/skills/, which Codex still reads. You can also place Skills in ~/.agents/skills/ — Codex reads both.

Easiest if Codex is already open

1
Copy the install prompt
Open the Skill on SkillsRadar, select Copy install prompt, then Copy.
2
Paste into Codex
Send it. Codex follows SkillsRadar’s install instructions.
Install prompt
```
Read https://skillsradar.dev/skills/<slug>/install.md and follow the instructions to install the skill.
```
You should see: You should see the version and folder under ~/.codex/skills/ or ~/.agents/skills/.

Check that Codex found it

1
Open the Skills list
In the CLI or IDE extension, type /skills, or type $ and start typing the name. In the ChatGPT desktop app, open Skills in the sidebar.
2
Restart if it doesn’t appear
Codex usually notices new Skills on its own. If one doesn’t show up, restart Codex.

How to run a Skill in Codex

1
Call it with $
Type $, the Skill’s name, then your request:
Codex CLI
```
$launch-page Parcelo, a parcel-tracking dashboard for small online shops
```
2
Or ask in plain words
Codex picks the Skill whose description matches. With many Skills installed, descriptions are shortened to fit about 2% of the context window — put the main use in the first sentence.

Where Codex looks for Skills

Day to day you’ll use personal and repository folders.

Scope	Location
Repository	.agents/skills/ from where you start Codex up to the repo root
Personal	~/.agents/skills/
Personal, older	~/.codex/skills/ (still read; SkillsRadar installs here)
Admin	/etc/codex/skills/
System	Bundled with Codex, such as $skill-creator and plan

Codex doesn’t merge two Skills with the same name. Both can appear in the picker — delete or rename the copy you don’t want.

Codex Skills vs AGENTS.md

Codex reads AGENTS.md at the start of every run. A Skill loads only when a task calls for it.

Loaded when needed

Skill

A folder in .agents/skills/ or ~/.codex/skills/
Loads when a task matches, or when you type $name
Good for repeatable, multi-step work

Read every run

AGENTS.md

~/.codex/AGENTS.md first, then one file per folder down to where you start
Closer files override earlier ones; ~32 KiB total by default
Good for short rules: test commands, code style, limits

Codex Skill not showing up?

A missing Skill is usually in the wrong folder or unpacked one level too deep.

Not in /skills

Move it to ~/.agents/skills/<name>/ or ~/.codex/skills/<name>/ and check for an extra ZIP level.

Listed without a description

Fix the frontmatter. Codex needs both name and description.

Project Skill missing

Start Codex from inside the repository.

$ finds nothing in ChatGPT desktop

Check /skills, restart, or try a copy in ~/.codex/skills/.

Common questions

Where are Codex Skills stored?

~/.agents/skills/ and ~/.codex/skills/ for personal Skills, .agents/skills/ inside a repository, and /etc/codex/skills/ for admins. SkillsRadar’s --agent codex target is ~/.codex/skills/.

What’s the difference between Codex Skills and AGENTS.md?

AGENTS.md is read at the start of every run. A Skill loads only when a task needs it.

Do Codex Skills work in ChatGPT?

Standalone Skills work in the ChatGPT desktop app, the Codex CLI, and the IDE extension. For ChatGPT on the web or mobile, ship the Skill inside a plugin.

How do I make my own Codex Skill?

Ask $skill-creator — it’s one of the system Skills bundled with Codex.

Also on Learn