Codex skills. Where they live and how to install them.

What skills are in Codex

OpenAI's documentation describes skills as the authoring format for reusable workflows in Codex and ChatGPT. A skill is a directory with a SKILL.md file that has a name and a description, plus optional scripts/, references/ and assets/ folders. Codex starts with each skill's name, description and file path, and reads the full SKILL.md only when it decides to use that skill. It builds on the open Agent Skills standard, so folders written for other agents usually work unchanged.

Standalone skill folders run in the Codex CLI, the IDE extension and the ChatGPT desktop app. Skills that are bundled inside a plugin are also available in ChatGPT on the web and on mobile.

Where Codex looks for skills

Codex follows symlinked skill folders. If two skills share a name, it does not merge them, and both can appear in the picker.

One detail to know: the bundled skill installer writes to $CODEX_HOME/skills, which defaults to ~/.codex/skills, and the skills CLI uses that folder for global installs. The documentation's list of locations does not include it, so if a globally installed skill does not appear, put it in ~/.agents/skills instead.

Install a skill

The examples use frontend-design from anthropics/skills, located at skills/frontend-design.

Option 1: the built-in installer

Type this inside Codex:

$skill-installer install https://github.com/anthropics/skills/tree/main/skills/frontend-design

The installer also accepts a curated skill by name, for example $skill-installer linear. Codex normally detects new skills on its own; if the skill does not show up, restart Codex.

Option 2: the skills CLI

npx skills add anthropics/skills --skill frontend-design -a codex

This installs into .agents/skills/ in the current project. Add -g for a global install into ~/.codex/skills/.

Option 3: GitHub CLI

gh skill install anthropics/skills frontend-design --agent codex
gh skill install anthropics/skills frontend-design --agent codex --scope user

Needs GitHub CLI 2.90.0 or later, where gh skill is a public preview.

Option 4: copy the folder

git clone --depth 1 https://github.com/anthropics/skills.git skills-src
mkdir -p .agents/skills
cp -r skills-src/skills/frontend-design .agents/skills/frontend-design
rm -rf skills-src

For a personal install, copy into ~/.agents/skills/ instead.

Check that it loaded

In the Codex CLI or the IDE extension, run /skills or type $ to see the list of skills, then mention the skill with $frontend-design. In the ChatGPT desktop app, open Skills in the sidebar. Codex can also pick a skill by itself when your request matches its description.

Update and remove

• Replace the folder with a newer copy, or reinstall with the same command.
• With the skills CLI: npx skills update and npx skills remove frontend-design.
• With gh: gh skill update.
• To switch a skill off without deleting it, add an entry to ~/.codex/config.toml and restart Codex:

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Troubleshooting

• The skill does not appear: restart Codex, then confirm the folder contains a file named exactly SKILL.md with name and description.
• Wrong folder: the documented repository location is .agents/skills, and Codex scans from the directory where you launch it up to the repository root, so a skill in a sibling folder is not seen.
• You have many skills and some are missing: the startup list is limited to about 2% of the context window (8,000 characters if the window is unknown). Codex shortens descriptions first and may omit skills with a warning, so keep descriptions short.
• You do not want automatic use: add agents/openai.yaml with policy.allow_implicit_invocation: false. The skill can still be called explicitly with $skill-name.

Safety

Skills can include scripts, and Codex runs them with the access your session has. Read SKILL.md and any files under scripts/ before installing, and only install from sources you trust. The $skill-installer and the other tools above download from GitHub, so check the repository and, where possible, pin a tag or commit. OpenAI's own openai/skills repository is marked deprecated in favour of openai/plugins, so check which one a tutorial points to.