Codex skills: where they live, how to install and write them

A Codex skill is a folder with a SKILL.md file in it: a short block of YAML that names the skill and says when to use it, then instructions in plain Markdown. Codex reads only each skill's name and description at the start of a session, and loads the full instructions when your task matches one or when you mention it with $ and its name. Put the folder in .agents/skills inside a repository, or in ~/.agents/skills to have it everywhere.

The pages that rank for "Codex skills" today are forum threads, a LinkedIn post and videos. This guide is the reference they point around: every folder Codex reads, how to install and write a skill, how to turn one off (including a mistake in OpenAI's own docs), and how to share one folder with Claude Code. Every path and setting below comes from OpenAI's documentation or the Codex source code, linked where it's used.

I build and sell skill packs that run in Codex and Claude Code, so I keep one set of skills working in both. This is what I'd want on the first day.

What is a Codex skill?

OpenAI describes a skill as "a directory with a SKILL.md file plus optional scripts and references" (OpenAI docs). Skills follow the open Agent Skills format, which Anthropic started and published, so the same folder can work in Codex, Claude Code, Cursor and Gemini CLI.

A skill folder looks like this:

release-notes/
├── SKILL.md          required: frontmatter and instructions
├── scripts/          optional: code the skill runs
├── references/       optional: documents Codex reads when it needs them
├── assets/           optional: templates, images, data
└── agents/
    └── openai.yaml   optional: Codex's own settings for the skill

And a complete SKILL.md:

---
name: release-notes
description: Drafts release notes from the git history since the last tag. Use when the user asks for release notes, a changelog entry, or what changed since the last release.
---

# Release notes

1. Find the last tag with `git describe --tags --abbrev=0`.
2. List the commits since it with `git log <tag>..HEAD --oneline`.
3. Group them under Added, Changed and Fixed. Leave out merge commits.
4. Show the draft. Don't write it to a file unless asked.

OpenAI's docs say "The SKILL.md file must include name and description." The Codex source is a little more forgiving: its parser rejects a skill with no description, but a missing name falls back to a default, and a name longer than 64 characters is an error (parser.rs). Write both anyway. Other tools need them, and the specification also wants the name in lowercase letters, numbers and hyphens, matching the folder name (specification).

Where does Codex look for skills?

OpenAI's docs list these locations (docs):

Codex walks every folder from where you started it up to the repository root, so a skill in packages/web/.agents/skills loads only when you work in that package, while one at the root loads everywhere in the repository.

Three details the docs mention only in passing:

• ~/.codex/skills still works, but it's the old location. The source code keeps it "for backward compatibility" and marks it deprecated (host_roots.rs). OpenAI's own $skill-installer still installs there, so you may end up with skills in both places.
• Linked folders work. "Codex supports symlinked skill folders and follows the symlink target when scanning these locations."
• Duplicate names don't merge. "If two skills share the same name, Codex doesn't merge them; both can appear in skill selectors." Give each skill a distinct name.

How does Codex decide when to use a skill?

The same way Claude Code does. In OpenAI's words: "ChatGPT and Codex start with each skill's name and description, then load the full SKILL.md instructions when they decide to use that skill." So the description decides whether a skill is ever used. Write it with the words people actually type, and put the main use first.

That list of names and descriptions has a budget: "this list uses at most 2% of the model's context window, or 8,000 characters when the context window is unknown." With many skills installed, descriptions get shortened to fit. You can change the budget with skills.max_context_tokens in config.toml; OpenAI's configuration reference says explicit values are capped at 10,000 tokens.

You can also call a skill yourself. "In Codex CLI or the IDE extension, run /skills or type $ to mention a skill," as in $release-notes.

For a skill that should only run when you ask, such as a deploy, turn off automatic use in agents/openai.yaml:

policy:
  allow_implicit_invocation: false

With that set, "Codex won't implicitly invoke the skill based on user prompt; explicit $skill invocation still works." The default is true.

How do you install a Codex skill?

There are three routes. Whichever you choose, read the skill first: see how to vet a skill in the Claude Code guide, since the checks are the same.

Copy the folder

Find the folder that holds the skill's SKILL.md and copy that folder, not the whole repository:

git clone https://github.com/<owner>/<repo>.git /tmp/<repo>
mkdir -p ~/.agents/skills
cp -r /tmp/<repo>/<path-to>/<skill-name> ~/.agents/skills/

Use .agents/skills/ inside a repository instead to install it for that project, and commit it so your team gets it too.

Ask the skill installer

Codex ships with a skill for installing skills. Mention it with the skill's name:

$skill-installer linear

By default it installs from OpenAI's curated set, and it can also install from any GitHub path you give it, including private repositories your git credentials can reach (skill-installer). It writes to ~/.codex/skills, and the skill is ready on your next turn.

The curated set lives in the openai/skills repository, which OpenAI marked deprecated in June 2026: "For current Codex skill and plugin examples, use the OpenAI Plugins repository." The installer still reads from it, but new skills from OpenAI now arrive as plugins.

Install a plugin

A plugin packages skills, and sometimes MCP servers and hooks, for installing in one step. Add a marketplace, then browse it with /plugins inside Codex (Build plugins):

codex plugin marketplace add owner/repo

The same command takes --ref to pin a branch or tag, a Git URL, or a local folder.

How do you write your own Codex skill?

1. Make the folder:

   mkdir -p ~/.agents/skills/release-notes

2. Save the SKILL.md from the top of this guide into it.
3. In a repository with a tag, ask Codex "what changed since the last release?" It should pick the skill up on its own. $release-notes runs it directly.

Or let Codex write the first draft: "In Codex, invoke it as: $skill-creator."

A few rules make the difference between a skill that fires and one that sits there:

• Say what it does and when to use it. OpenAI's own template reads: "Explain exactly when this skill should and should not trigger."
• Keep SKILL.md short and move detail into references/, saying in SKILL.md when to read each file. Only the name and description cost anything until the skill is used.
• Add agents/openai.yaml only when you need it. It holds a display name, icons and a default prompt for the ChatGPT desktop app, the allow_implicit_invocation policy above, and the MCP tools the skill depends on. Other tools ignore it.

How do you turn a Codex skill off?

Add a [[skills.config]] entry to ~/.codex/config.toml, then restart Codex. OpenAI's docs say to restart "after changing ~/.codex/config.toml." You can pick the skill by name:

[[skills.config]]
name = "release-notes"
enabled = false

Or by path, and here the docs disagree with each other. The skills page points path at the SKILL.md file:

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

The configuration reference shows the skill's folder instead. The source settles it: Codex compares each rule with the path of every loaded skill's SKILL.md file (host_service.rs), so point path at the file. A folder path matches nothing, and the skill stays on.

Three more rules from the same code (skills_config.rs):

• Use name or path, never both. An entry with both, or with neither, is ignored with a warning.
• Later entries win over earlier ones for the same skill.
• Only your user config counts. Codex reads these rules from ~/.codex/config.toml and from settings passed on the command line, not from a project's config file. To keep a skill out of one repository, remove it from that repository's .agents/skills folder.

Do skill scripts get special permission?

No. A skill's scripts run like any other command Codex runs, under the same sandbox and approval settings. OpenAI's own installer skill says as much: "All of these scripts use network, so when running in the sandbox, request escalation when running them."

That cuts both ways. A skill can't quietly run something your settings would have blocked. But if you've given Codex wide permissions, a skill's scripts get them too, which is why reading a skill before you install it matters.

Codex skills and Claude Code skills

The format is shared, so one skill folder can serve both tools. What differs:

Claude Code doesn't read .agents/skills, so keep one copy of each skill and link it into both folders:

mkdir -p ~/.claude/skills ~/.agents/skills
ln -s ~/skills/release-notes ~/.claude/skills/release-notes
ln -s ~/skills/release-notes ~/.agents/skills/release-notes

Both tools document support for linked skill folders. Write the frontmatter to the specification, with a lowercase name that matches the folder and a description under 1,024 characters, and each tool ignores the other's extras. The Claude Code skills guide covers the Claude side in full.

Skills vs AGENTS.md

AGENTS.md is read once, at the start of every run: Codex "builds an instruction chain when it starts," from ~/.codex/AGENTS.md and from each folder between the repository root and where you are, up to 32 KiB by default (AGENTS.md docs). A skill costs only its name and description until it's needed.

So put the rules that always apply in AGENTS.md: how to run the tests, what never to commit, how the repository is laid out. Put procedures you run sometimes, like a release or a migration, in skills. If AGENTS.md keeps growing with step-by-step instructions for one kind of task, that section wants to be a skill.

Running Codex beside Claude Code or Gemini CLI on one repository? The Agent Setup Pack gives all three one set of rules and checks what each actually loads, gives each agent its own git worktree, and keeps API keys out of the chat. The verification skill is free if you'd like to try one of our skills in Codex first.

Troubleshooting Codex skills

It doesn't show up. Check that the folder sits directly in one of the locations above (.agents/skills/<name>/SKILL.md, not a folder deeper), that --- is the first line of SKILL.md, and that it has a description. Then run /skills to see the skills Codex found. If you just added it and it still isn't there, restart Codex.

It never triggers on its own. Read the description as if you were Codex: does it contain the words you used? Check that agents/openai.yaml doesn't set allow_implicit_invocation: false. With many skills installed, descriptions are shortened to fit the list's budget, so put the key use first.

A skill you turned off still runs. Check that the rule is in ~/.codex/config.toml, not a project config file, that a path points at SKILL.md and not the folder, and that you restarted Codex.

Two skills with the same name. Codex keeps both. Rename one, or turn one off by path.

An installed skill is in a folder you didn't expect. $skill-installer writes to ~/.codex/skills, the older location. Codex still reads it; move the folder to ~/.agents/skills if you'd rather keep everything in one place.

Frequently asked questions