The short answer
- 1Put the Skill’s folder in
~/.agents/skills/to use it in every repository, or in a repo’s.agents/skills/to keep it there. - 2Codex needs both
name(up to 64 characters) anddescription(up to 1,024) inSKILL.md. - 3Type
$plus the Skill’s name to run it, or/skillsto pick from a list.
Before you start
Skills work in three places: the Codex CLI, the Codex IDE extension, and Codex in the ChatGPT desktop app. To install from Skillry with the CLI, you also need macOS or Windows and Node.js 22 or newer.
How to add Skills to Codex
Codex and the Skillry CLI use the same default folder, ~/.agents/skills/, so you don’t need any extra flag. Pick whichever route suits you.
- 1
Open the Skill on Skillry, select Copy install prompt, then select Copy in the dialog.
- 2
Paste it into Codex and send it. The agent reads Skillry’s install instructions and runs the right command itself.
Install prompt Read https://skillry.dev/skills/<slug>/install.md and follow the instructions to install the skill. - 3
When your browser asks you to approve a device code, approve it.
You should see: Codex reporting the version it installed and the folder it used, under
~/.agents/skills/.
- 1
Sign in once. A browser window opens with a device code for you to approve.
Terminal npx --yes skillry-cli@latest login - 2
Install. You don’t need a flag, because the CLI’s default folder is the one Codex reads.
Terminal npx --yes skillry-cli@latest install <slug>You should see:
Installed <slug> <version> to ~/.agents/skills/<slug>
Select Download ZIP on the Skill’s page, or use a Skill folder you got somewhere else. Read SKILL.md and anything in scripts/ before you install, since the agent follows those instructions and can run those scripts. Then move the whole folder:
mkdir -p ~/.agents/skills
mv ~/Downloads/my-skill ~/.agents/skills/ZIPs often unpack with an extra level, like my-skill/my-skill/SKILL.md. SKILL.md has to sit directly inside the Skill’s folder, or the agent won’t find it.
Codex also has its own installer for OpenAI’s catalog, $skill-installer. It puts Skills in ~/.codex/skills/, an older folder Codex still reads, so Skills from both installers show up together.
Check that Codex found it
In the CLI or the IDE extension, type /skills, or type $ and start typing the name. In the ChatGPT desktop app, open Skills in the sidebar. Codex notices new Skills on its own; if one doesn’t appear, restart Codex.
How to run a Skill in Codex
Type $, the Skill’s name, and then your request:
$launch-page Parcelo, a parcel-tracking dashboard for small online shopsOnce you know it works, you can ask in plain words and Codex picks the Skill whose description matches. With many Skills installed, Codex shortens descriptions so the whole list fits in about 2% of the context window. Put the main use in the first sentence of a description so it survives the cut.
Where Codex looks for Skills
Codex gathers Skills from five scopes. Day to day you’ll use two of them: your personal folder and the repository’s.
| Scope | Location |
|---|---|
| Repository | .agents/skills/ in every folder from where you start Codex up to the repo root |
| Personal | ~/.agents/skills/ |
| Personal, older | ~/.codex/skills/, still read (missing from the docs, but confirmed in Codex’s source) |
| 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, so delete or rename the copy you don’t want.
Codex Skills vs AGENTS.md
Codex reads AGENTS.md at the start of every run, so it suits short rules that always apply. A Skill loads only when a task calls for it, so it suits longer procedures you repeat.
Loaded when needed
- A folder in
.agents/skills/ - Loads when a task matches, or when you type
$name - Good for repeatable, multi-step work
Read at the start of every run
~/.codex/AGENTS.mdfirst, then one file per folder from the repo root down to where you start- Files closer to you override earlier ones; 32 KiB total by default
- Good for short rules: test commands, code style, limits
A split that works well: keep AGENTS.md to about a screen of rules, and move anything step-by-step into Skills. Skills vs instructions goes deeper.
Codex Skill not showing up? Match your symptom
A missing Skill is usually in the wrong folder or unpacked one level too deep. Find what you’re seeing in the left column.
| What you see | Fix |
|---|---|
Not in /skills | Move it to ~/.agents/skills/<name>/ and check for an extra level from the ZIP |
| 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 the ChatGPT desktop app | A reported bug (openai/codex#28505). Check /skills, restart, or try a copy in ~/.codex/skills/ (we haven’t tested this yet) |
Common questions
Where are Codex Skills stored?
~/.agents/skills/ for your own Skills, .agents/skills/ inside a repository, and /etc/codex/skills/ for admins. Codex also reads the older ~/.codex/skills/, which is where $skill-installer puts 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. To use one in ChatGPT on the web or on mobile, ship it inside a plugin.
How do I make my own Codex Skill?
Ask $skill-creator. It’s one of the system Skills that come bundled with Codex.
Sources
Did this guide help?
