Codex Skills: How to Add and Use Agent Skills in OpenAI Codex

Codex has skills, and installing one takes a single command. A skill is a folder with a SKILL.md file that Codex reads when a task matches it, and you can add one from GitHub with $skill-installer, the skills CLI, gh skill, or a plain folder copy. This guide covers where Codex looks for skills, each install method, how to check that a skill loaded, and which skills from the directory are good first picks.

If you only want the commands, jump to the install section. If a skill you added does not show up, the troubleshooting section lists the usual causes in order.

What are Codex skills?

OpenAI's documentation describes skills as the authoring format for reusable workflows in Codex and ChatGPT. Each skill is a directory containing a SKILL.md with a name and a description, plus optional scripts/, references/ and assets/ folders. The format comes from the open Agent Skills specification, which is why the same folder can work in several agents.

Codex does not read every skill in full at startup. It begins with each skill's name, description and file path, and opens the whole SKILL.md only when it decides the skill fits your request. That keeps the context window free until a skill is needed, so a long reference document inside a skill costs almost nothing until the agent loads it.

Standalone skill folders run in the Codex CLI, the IDE extension and the ChatGPT desktop app. Skills that are bundled inside a plugin also reach ChatGPT on the web and on mobile. The Codex page in this directory keeps the full list of paths and install commands, verified against the docs.

Where does Codex look for skills?

Codex checks four scopes, and you choose one by choosing where the folder goes.

Because Codex scans from the directory where you launch it up to the repository root, a skill in a sibling folder is not seen. Codex also follows symlinked skill folders. If two skills share a name, Codex does not merge them, and both can appear in the picker.

One detail catches people out. The bundled installer writes to $CODEX_HOME/skills, which defaults to ~/.codex/skills, and the skills CLI uses that folder for global installs. OpenAI's list of discovery locations does not include it. If a globally installed skill does not appear, move it into ~/.agents/skills.

How do you install a skill in Codex?

The examples below use frontend-design from anthropics/skills, which sits at skills/frontend-design in that repository. Swap in any skill you like.

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 the name of a curated skill, for example $skill-installer linear. Codex normally detects new skills on its own. If yours does not appear, 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, which writes to ~/.codex/skills/. The command comes from the vercel-labs/skills project.

Option 3: GitHub CLI

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

gh skill needs GitHub CLI 2.90.0 or later and is in public preview. The default scope is the project, and --scope user installs for your account. The gh skill install manual lists the other flags, including --pin to lock a tag or commit.

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. Commit the folder if you want teammates to get the skill with the repository.

Which method should you pick? Use the installer when you are already in a Codex session, gh skill when you want version pinning and update checks, and the manual copy when you want to read every file before it lands in your project.

How does Codex choose and run a skill?

There are two routes. With explicit invocation, you type $skill-name in the Codex CLI or IDE extension, or @skill-name in ChatGPT. With implicit invocation, Codex compares your request with every skill description and loads the best match on its own.

Implicit use depends entirely on the description, so a skill with a vague one rarely triggers. If you author skills yourself, say what the skill does and when to use it, and name the trigger phrases a user would type. The skill authoring topic lists skills that help with this, and the SKILL.md format reference covers the field limits.

To confirm a skill loaded, run /skills in the CLI or IDE extension, or type $ to see the list. In the ChatGPT desktop app, open Skills in the sidebar. Then mention the skill by name and watch whether Codex follows its steps.

Keeping the startup list small

Codex limits the skill list it shows the model at startup to about 2% of the context window, or 8,000 characters when the window size is unknown. With many skills installed, Codex shortens descriptions first and may leave some skills out with a warning. Short, specific descriptions and a trimmed set of installed skills avoid this.

Turning automatic use off

Some skills should only run when you ask. Add an agents/openai.yaml file inside the skill with policy.allow_implicit_invocation: false, and Codex will run it only for an explicit $skill-name. The same optional file can also hold interface metadata and tool dependencies.

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

Which skills should you try first?

The directory lists skills by job, and any skill that follows the open format is a candidate for Codex. The picks below are described from their listings and repositories. We have not run each of them inside Codex, so read a skill's own README for agent-specific notes before you rely on it.

The PDF skill is listed under a proprietary licence reference, so check the licence file in its repository before you copy it into a shared project. All six show a passing result on the directory's automated safety check at the time of writing. That check is a screen, not a guarantee, and reading SKILL.md and any scripts/ folder yourself is still the real test.

For more options, browse the most-used skills, the agent workflows category, or the agent instructions topic if what you need is a standing rule rather than a skill. A skill that finds other skills, find-skills, uses the npx skills CLI to search and install.

What if a Codex skill does not show up?

Work through these in order.

1. Restart Codex. Codex usually notices new skills, but a restart is the quickest fix.
2. Check the file name. The file must be named exactly SKILL.md, with name and description in its frontmatter.
3. Check the folder. Use .agents/skills in the repository or your home directory. A skill in a sibling folder is not scanned, and a global install from the CLI may sit in ~/.codex/skills, which the documentation does not list.
4. Check how many skills you have. With a long list, Codex may shorten or omit entries to stay inside its startup budget.
5. Check for a disable entry. A [[skills.config]] block with enabled = false hides a skill until you remove it and restart.

Is it safe to install a skill?

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

Update and remove skills

• Replace the folder with a newer copy, or reinstall with the same command.
• skills CLI: npx skills update and npx skills remove frontend-design.
• GitHub CLI: gh skill update checks the source repository for changes using metadata written into the installed skill.
• Manual copies: delete the folder.

If you are also setting up other agents, the same skill folder can usually be shared. The Claude Code install guide shows the equivalent steps there, and what are Claude skills explains the format behind all of them.