Codex Skills: The Practical Guide

What Codex skills are

Codex is OpenAI's coding agent — a CLI that also runs as IDE extensions and inside ChatGPT. A skill is a directory containing a SKILL.md file: YAML frontmatter telling Codex when to use it, plus markdown instructions to follow once it does.

Codex implements the Agent Skills open standard, the same SKILL.md format used by Claude Code, Hermes Agent, Cursor and others. A well-formed skill written for one of those often works in Codex unchanged. What differs is everything around the file: where it lives, how it's invoked, and what metadata Codex understands.

The minimum viable skill is two frontmatter fields:

---
name: skill-name
description: When this skill should and should not trigger.
---

Skill instructions for ChatGPT or Codex to follow.

A full skill directory:

my-skill/
├── SKILL.md              # required
├── scripts/              # optional: executable code
├── references/           # optional: documentation
├── assets/               # optional: templates, resources
└── agents/
    └── openai.yaml       # optional: Codex/ChatGPT UI + policy metadata

Where skills live, and why you'll see two different answers

This is the part almost every guide to Codex skills gets wrong, so it's worth being precise.

The official documentation lists the user-level skills directory as $HOME/.agents/skills. Most third-party writeups instead tell you to use ~/.codex/skills. Both directories really are scanned — but they are not equivalent, and the Codex source says so directly.

In codex-rs/ext/skills/src/host_roots.rs, the branch that assembles user-scope roots carries this comment:

// Deprecated user skills location (`$CODEX_HOME/skills`), kept for backward
// compatibility.

$CODEX_HOME defaults to ~/.codex (overridable by the CODEX_HOME environment variable — confirmed in codex-rs/core/src/config/mod.rs). So ~/.codex/skills is the older location, still scanned so existing setups keep working, while ~/.agents/skills is the current one. The .agents/ convention is deliberately cross-agent: Hermes Agent reads the same directory when you add it to its external_dirs.

The wrinkle: OpenAI's own bundled skill-installer still installs to the deprecated path. Its SKILL.md states it "Installs into $CODEX_HOME/skills/<skill-name> (defaults to ~/.codex/skills)." Nothing breaks — the deprecated root is still scanned — but it does mean an installed skill and a hand-written one can end up in different directories on the same machine.

Practical rule: put skills you write by hand in .agents/skills. Expect $skill-installer to use ~/.codex/skills. Check both when a skill doesn't appear.

Every location Codex scans

The documentation gives a simplified table. This is the full set, read from resolve_skill_roots in the source (results are de-duplicated by path):

Scope	Location	Notes
Repo	`<dir>/.agents/skills` for every directory from the project root down to your working directory	Not just three fixed levels — Codex probes the whole chain
Repo	`<project config folder>/skills`	From the project config layer
User	`$HOME/.agents/skills`	Current user-level location
User	`$CODEX_HOME/skills` (`~/.codex/skills`)	Deprecated, kept for backward compatibility
Admin	System config folder + `/skills`	Documented as `/etc/codex/skills`
System	A cache root under `$CODEX_HOME`	Internal
Plugin	Skill directories contributed by installed plugins

Symlinks are followed when scanning, so you can keep a skills repo elsewhere and link it in.

Two consequences worth knowing. Project root is determined by configurable project root markers, so the repo chain depends on how your project is detected. And when two skills share a name, both appear in the selector without merging — Codex has no precedence rule that silently picks a winner, which is a real difference from Claude Code's enterprise-over-personal-over-project chain.

How Codex decides to use a skill

Two paths, and the distinction matters when you're writing one:

Explicit — you invoke it. Type $ in the Codex CLI or IDE to mention a skill, or $skill-name directly. In ChatGPT, it's @ instead.
Implicit — Codex picks it. If your task matches the skill's description, Codex can load it without being asked.

That makes description the single most important field in the file. The official guidance is to "explain exactly when this skill should and should not trigger," and the curated skills follow it closely — security-threat-model, for instance, spends half its description on negative triggers ("Do not trigger for general architecture summaries, code review, or non-security design work").

You can turn implicit invocation off per skill via agents/openai.yaml:

policy:
  allow_implicit_invocation: false

That's the setting to use for anything with side effects — deploys, publishes, anything you want a human to trigger deliberately.

The context budget that shapes everything

Codex loads only each skill's name and description up front, then pulls the full SKILL.md when it decides to use one. That index is capped: 2% of the context window, or 8,000 characters, whichever is smaller.

This is a real constraint, not trivia. Install enough skills and descriptions start competing for a fixed budget — which is why a vague, sprawling description is a functional problem and not just untidy writing. See how to create a Codex skill for how to write against it.

The optional Codex-specific metadata

agents/openai.yaml is where Codex and ChatGPT-specific presentation and policy live. It's entirely optional — a skill without it works fine — and it's the piece that doesn't travel to other agents:

interface:
  display_name: "User-facing name"
  short_description: "User-facing description"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Optional surrounding prompt"

policy:
  allow_implicit_invocation: false

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"

That dependencies.tools block is how a skill declares it needs an MCP server — which is the cleanest way into the next question.

Skills vs AGENTS.md vs MCP vs plugins vs prompts

Five things that get conflated constantly. In Codex they do genuinely different jobs:

Concept	What it is	When it loads
AGENTS.md	Persistent project context — setup commands, conventions, standards	Always, before work starts
Skill	A packaged procedure plus optional scripts and references	Only when invoked or description-matched
MCP server	An external protocol connection that gives Codex new tools	Configured separately; a skill can declare one as a dependency
Plugin	A distributable bundle that can carry skills, connectors and config together	When installed and enabled
Prompt	What you type	Immediately, once

The distinction that actually costs people time is the first two. AGENTS.md is always in context and capped at 32 KiB combined; skills cost only a name and description until they're needed. That asymmetry is the whole decision rule, and it's covered properly in Codex skills vs AGENTS.md — including the fact that OpenAI's own documentation never actually compares them.

Turning a skill off

Skills are enabled by default. To disable one without deleting it, add an entry to ~/.codex/config.toml:

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

Restart Codex after changing it.

What ships with Codex

Codex bundles a set of skills you don't install. As of the current openai/codex source, the bundled samples are imagegen, openai-docs, plugin-creator, review-agent, skill-creator, and skill-installer.

Two of those are how you get everything else: $skill-creator writes new skills, $skill-installer fetches existing ones. Note that this list comes from the Codex repository itself, not from the separate catalog repo — which matters, because that catalog has since been deprecated. See the best Codex skills for what's actually in it and what the deprecation means.

Common questions

Do I need to restart after adding a skill? Yes, per the official docs ("Restart Codex after changes") and the bundled installer, which tells you an installed skill will be available "on their next turn." Some third-party guides claim restarts are no longer needed; that contradicts both first-party sources as of August 2026, so we're going with the sources.

Why doesn't my skill show up? Most often it's in the wrong directory — check both .agents/skills and ~/.codex/skills. Beyond that, confirm SKILL.md is named exactly that and has valid frontmatter.

Can I keep skills in my repo? Yes — .agents/skills at any level between your project root and working directory. That's the mechanism for committing skills alongside a codebase so the whole team gets them.

Limitations and caveats

We have not run Codex or installed any skill. Everything here is either documented behavior or verified in the openai/codex source, and this page says which throughout.
The deprecation of $CODEX_HOME/skills is a comment in the source, not a formal announcement in OpenAI's prose documentation. We're quoting the code and attributing it as such.
Codex is moving fast — the skills documentation itself moved hosts recently (developers.openai.com/codex/skills now redirects to learn.chatgpt.com). Paths and behavior described here reflect the source and docs as of August 2026.

Sources

Codex — Build skills (official docs)
Codex — AGENTS.md (official docs)
openai/codex — codex-rs/ext/skills/src/host_roots.rs — skill-root resolution and the deprecation comment
openai/codex — bundled sample skills
agentskills.io — the open standard Codex implements