Where Codex skills live and how to install them safely

What are Codex skills?

Codex skills are folders with a SKILL.md file that Codex loads when a task matches the skill’s description. Put a skill in .agents/skills/ inside your repo, or in ~/.agents/skills/ to use it everywhere, and Codex picks it up. You can also install one with $skill-installer <name> inside Codex, or run npx skills add owner/repo -a codex from a terminal.

OpenAI Codex skills use the shared Agent Skills format, so most skills written for Claude Code or Cursor work here without changes. What differs is the folder, the install route and a few Codex-only settings. Those are covered below. Of the 195 repositories we have reviewed, 138 say they support Codex.

Where Codex looks for skills

According to the Codex skills documentation, Codex scans four places:

• Repository: .agents/skills in the current working directory, in its parent directory, and at the repository root.
• User: $HOME/.agents/skills.
• Admin: /etc/codex/skills.
• System: skills bundled with Codex itself.

Two skills with the same name are not merged. Both show up in the selector, so give your own skills distinctive names. Symlinked skill folders are followed.

How Codex decides to use a skill

A skill has to be found before it can help, and Codex keeps that cheap. At startup it reads only each skill’s name, description and file path. The full SKILL.md is read only after Codex selects the skill. The initial list is capped at 2% of the context window (8,000 characters when the window size is unknown), and descriptions get shortened first if you install many skills. The skills.max_context_tokens setting raises that budget up to 10,000 tokens.

You can trigger a skill two ways. Explicitly: type $ in the Codex CLI or IDE extension and name the skill, or open /skills. Implicitly: Codex matches your task against the description. So the description is the part of a skill worth reading first. A vague one means the skill fires at the wrong time or never.

An optional agents/openai.yaml file sets invocation policy and UI metadata for the ChatGPT desktop app. Setting policy.allow_implicit_invocation: false stops automatic matching, while $skill-name still works.

Installing Codex skills

There are three routes, and which to use depends on where the skill lives.

Inside Codex, $skill-installer linear installs the curated Linear skill. Codex normally detects new skills on its own; restart it if the skill doesn’t appear.

For any GitHub repo, the skills CLI copies a skill into the right folder:

npx skills add owner/repo -a codex
npx skills add owner/repo -a codex -g

The first command writes to .agents/skills/ in the project. The second, with -g, writes to ~/.agents/skills/.

Or copy the skill folder (with its SKILL.md) into either location by hand.

Is there a Codex skills marketplace?

OpenAI’s own catalog is the openai/skills repository, split into .system (built in), .curated (installable by name) and .experimental (installable by folder or URL). Its README now marks the repository deprecated and points to openai/plugins for current examples, with a “Build plugins” guide that covers skill-only plugins. Beyond that, skills are spread across GitHub and third-party directories such as this one.

Plugins and skills

The deprecated catalog’s README sends people building their own skills to the “Build plugins” guide, which describes a skill-only plugin. In practice a skill can ship alone, as a folder in .agents/skills/, or inside a plugin that carries more than instructions. If a repo offers both, the plain folder is the easier one to read before you install it. Our plugins page explains how the two differ on the Claude Code side.

When a Codex skill doesn’t show up

Work through these in order:

1. The folder sits in one of the four scanned locations, and the file is called SKILL.md.
2. The frontmatter has both name and description. Both are required.
3. Another skill with the same name is not shadowing it. Duplicates both appear in the selector, so look there.
4. ~/.codex/config.toml doesn’t contain a [[skills.config]] entry with enabled = false for it.
5. You restarted Codex after installing.

If the skill appears but never fires on its own, rewrite the description. Say what the skill does and name the trigger words up front. Codex’s docs recommend exactly that, since the description is all Codex sees until it selects the skill.

Turning a Codex skill off

To disable a skill without deleting it, add an entry to ~/.codex/config.toml and restart Codex:

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

What a Codex skill can access

A SKILL.md is text, but a skill folder often carries scripts/, and those run with the permissions of your session. A skill can also tell Codex to fetch instructions from the web at run time, which means the skill you reviewed is not always the skill that runs.

That is why we record, for every skill, what it runs, what it sends and where, and what we could not read. Among the 138 repositories that list Codex, 6 had no issues in our review, 84 are marked “review before installing” and 48 are marked “broad access”. Two examples:

• mattpocock/skills is one of the most installed engineering packs. Its few scripts are small, and nothing in it makes network calls on its own. Verdict: install.
• trailofbits/skills is expert-written and evaluated, but several of its skills pre-approve unrestricted shell access and one scanner sends live requests. We mark it “broad access” and suggest picking plugins for your stack instead of installing all 97 skills.

A skill for one agent can rely on features another agent lacks. The skills CLI notes that allowed-tools, context: fork and hooks vary by agent. If a skill depends on one of them, check that Codex honors it before trusting the skill’s safety claims.

Read the security checklist before installing from an unfamiliar repo, and see how we review for what our statuses mean. The best skills list and the full skills directory show the same ratings. The pack list further down this page is filtered to repositories that mention Codex. If you are unsure how the file itself is structured, see the SKILL.md format guide.