SkillsPicker

Home / Guides

Codex skills

Codex reads skills in the open SKILL.md format, the same format Claude Code uses. A skill is a folder with a SKILL.md file of instructions, plus optional scripts and reference files. Codex looks for those folders in .agents/skills/.

This guide covers where Codex loads skills, how to install and call them, and how to reuse skills written for Claude Code. Facts come from the Codex skills docs, read on October 23, 2026.

Where Codex loads skills

Scope Location Use
Repo $CWD/.agents/skills Skills for the folder where you start Codex
Repo $CWD/../.agents/skills Skills for a shared parent folder in a repo
Repo $REPO_ROOT/.agents/skills Skills for everyone who works in the repo
User $HOME/.agents/skills Your own skills for every repo
Admin /etc/codex/skills Skills for every user on a machine or container
System Bundled with Codex Built-ins such as skill-creator

Codex scans .agents/skills in every folder from where you start up to the repo root. It follows symlinks. If two skills share a name, Codex keeps both, and both show in the picker.

Note the folder name: .agents, not .codex and not .claude.

How to install a Codex skill

Copy the folder. Put the skill folder in .agents/skills/ in your repo, or in ~/.agents/skills/ for every repo. The folder must hold SKILL.md at its top level.

Use the built-in installer. In Codex, run $skill-installer with a skill name. The docs give $skill-installer linear as an example. You can ask it to pull skills from other repos.

Use the skills CLI. The open source skills CLI installs from GitHub:

npx skills add owner/repo --skill skill-name --agent codex
npx skills add owner/repo --skill skill-name --agent codex -g

The -g flag installs to your user folder in place of the project.

The docs say Codex picks up new skills on its own. If one does not appear, restart Codex.

How to use skills in Codex

The docs list two ways:

  1. Call it by name. In Codex CLI or the IDE extension, run /skills or type $ and pick the skill.
  2. Let Codex choose. Codex reads each skill's name and description at start. When your request matches a description, it loads the full SKILL.md.

Write descriptions with the trigger words up front. The docs say Codex shortens descriptions first when many skills are installed.

How much context skills use in Codex

The docs say the first skills list uses up to 2% of the model's context window, or 8,000 characters when the window size is unknown. You can change the budget with skills.max_context_tokens, up to 10,000 tokens. With a large set, Codex may leave some skills out of the list and show a warning. The budget covers the list. A skill Codex picks loads in full.

To turn a skill off without deleting it, add this to ~/.codex/config.toml and restart Codex:

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

How to use Claude skills in Codex

Claude Code and Codex both follow the Agent Skills spec. A skill written to that spec works in both.

  1. Copy or symlink the folder from .claude/skills/<name>/ to .agents/skills/<name>/. Codex follows symlinks, so one copy can serve both agents.
  2. Check the front matter. The spec fields are name, description, license, compatibility, metadata, and allowed-tools. The Claude Code docs list extra fields such as disable-model-invocation and context: fork. Those are Claude Code features.
  3. Check the body. A line such as !`git diff HEAD` is Claude Code's dynamic context injection, a Claude Code feature. Do not count on Codex to run it. Rewrite it as a step: "Run git diff HEAD and read the output."
  4. Install with npx skills add owner/repo --agent codex claude-code to put the skill in both places in one step.

Options for Codex alone

A skill can include agents/openai.yaml. It sets a display name, icons, and a default prompt for the ChatGPT desktop app. It can set allow_implicit_invocation: false so Codex runs the skill when you call it by name and not on its own. It can list tool needs, such as an MCP server URL.

The docs suggest plugins when you want to share skills beyond one repo. A plugin can bundle several skills with MCP server settings.

Find skills for your project

SkillsPicker indexes open-license SKILL.md files from public GitHub repos and matches them to your stack. See skills for Codex for install commands, or run the free scan on your repo. It shows the match count and 2 picks, or the full list free when we have few skills for your stack. You can add the SkillsPicker MCP server to Codex in ~/.codex/config.toml:

[mcp_servers.skillspicker]
url = "https://skillspicker.com/mcp"

FAQ

Where are Codex skills stored? In .agents/skills/ in your repo, ~/.agents/skills/ for your user, and /etc/codex/skills for a whole machine.

How do I call a skill in Codex? Type $ and the skill name, or run /skills. Codex can pick a skill when your request matches its description.

Can I use Claude Code skills in Codex? Yes. Copy or symlink the folder into .agents/skills/. Spec fields work in both. Fields for Claude Code alone and !` command lines do not apply in Codex.

Does Codex have a skills marketplace? Codex ships $skill-installer for curated skills, and it shares a plugin directory with ChatGPT for packaged skills.

Checked 2026-10-23. Prices and policies change. Confirm on the source before you buy.

Sources

More guides