What are Codex skills? How they load, where they live and how to use them

The short answer

A Codex skill is a folder that teaches Codex one kind of task. At its center is a file called SKILL.md: a few lines of YAML frontmatter with a name and a description, followed by Markdown instructions. The folder can also carry scripts Codex runs, reference documents it reads on demand, and templates or other assets.

Skills follow the open Agent Skills format, so the same folder works in other agents that read that format. In Codex they are available in the CLI, the IDE extension and Codex in the ChatGPT desktop app.

The reason skills exist is context. You could paste a 200-line release checklist into every prompt, or keep it in AGENTS.md where it loads into every session whether you are releasing or fixing a typo. A skill keeps that checklist out of the way until the task needs it.

What is inside a skill folder

release-notes/
├── SKILL.md            # required: frontmatter + instructions
├── scripts/            # optional: code Codex can run
│   └── collect_prs.py
├── references/         # optional: docs Codex reads when needed
│   └── style.md
├── assets/             # optional: templates, schemas, images
│   └── template.md
└── agents/
    └── openai.yaml     # optional: Codex UI metadata, invocation policy, tool dependencies

A minimal SKILL.md looks like this:

---
name: release-notes
description: Drafts user-facing release notes from merged pull requests since the last tag. Use when the user asks for release notes, a changelog entry or a "what shipped" summary.
---

1. Find the last tag with `git describe --tags --abbrev=0`.
2. Run `scripts/collect_prs.py <tag>` to list merged PRs.
3. Group entries as Added, Changed, Fixed. Follow references/style.md.
4. Write the result to RELEASE_NOTES.md and show the diff.

Only name and description are required. The SKILL.md format reference covers every field, naming rules and the optional agents/openai.yaml file.

How Codex loads skills

Codex uses progressive disclosure: it reveals a skill in stages instead of loading everything at startup.

Stage	What Codex has in context	When
Catalog	Each skill’s name, description and file path	At the start of a session
Instructions	The full SKILL.md body	When Codex selects the skill or you mention it
Resources	Files from references/, output of scripts/, assets	Only when the instructions call for them

The catalog has a budget. By default it uses at most 2% of the model’s context window, or 8,000 characters when the window size is unknown. When many skills are installed, Codex shortens descriptions first; with a very large set it may leave some skills out of the catalog and show a warning. You can change the budget with skills.max_context_tokens in ~/.codex/config.toml, up to 10,000 tokens:

[skills]
max_context_tokens = 6000

The budget only covers the catalog. Once a skill is selected, Codex reads its whole SKILL.md, which is why a skill’s body should stay focused and push long material into references/.

Two practical consequences follow. First, the description does most of the work: it is the only text Codex sees when deciding whether a skill applies, so it needs the trigger words a user would actually type. Second, installing hundreds of skills is not free. Each one adds a line to the catalog, and past the budget the descriptions get trimmed, which makes implicit matching less reliable. The troubleshooting guide covers both.

Where Codex looks for skills

Scope	Location	Typical use
Repo	.agents/skills in the working directory	Skills for one service or module
Repo	.agents/skills in each parent folder up to the repository root	Skills shared by a part of a monorepo, or by the whole repo at the root
User	~/.agents/skills	Your personal skills, available in every repository
Admin	/etc/codex/skills	Skills for every user on a machine or container
System	Bundled with Codex	Built-ins such as skill-creator

A few details matter in practice:

• Symlinks are followed. You can keep skills in one git checkout and link them into ~/.agents/skills.
• Names are not merged. If two skills share a name, Codex keeps both and both can appear in the picker. Pick unique names.
• Changes are picked up automatically. If an edited or newly installed skill does not show up, restart Codex.
• Older installs. Earlier Codex releases used ~/.codex/skills. Current Codex still reads that folder for backward compatibility, but new skills belong in ~/.agents/skills.
• Cloud tasks. Skills committed to the repository are available in Codex cloud tasks. Personal skills from your machine are not synced to cloud environments.

Plugins add one more source: an installed Codex plugin can bundle skills, which become available in the next session after install.

Using a skill

There are two ways a skill gets used.

Explicit invocation. In the CLI or IDE extension, type $ and the skill name, or run /skills to browse the list and insert one:

$release-notes since v2.3.0, skip dependency bumps

This always loads the skill, regardless of how well your wording matches its description. Use it when you know which skill you want.

Implicit invocation. Codex compares your request against the catalog and loads a skill on its own when the task matches its description. Asking “write the release notes for this sprint” should pull in the release-notes skill without you naming it.

A skill author can turn implicit use off. Setting allow_implicit_invocation: false under policy in agents/openai.yaml means Codex only loads the skill when you mention it with $. That suits skills with side effects, such as deploy or publish workflows.

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

[[skills.config]]
path = "/Users/you/.agents/skills/release-notes/SKILL.md"
enabled = false

Skills compared with AGENTS.md and MCP

Codex has several ways to shape its behavior, and they are meant to be combined:

Mechanism	Loaded	Best for
AGENTS.md	Every session, before any work	Build and test commands, conventions, boundaries that always apply
Skill	Catalog always, body on demand	Repeatable procedures, domain knowledge, scripts
MCP server	Tools listed when the server starts	Live access to external systems: issue trackers, browsers, docs
Plugin	Installed as a package	Distributing skills together with MCP servers and other parts

A useful rule: if Codex should know it on every task, it goes in AGENTS.md. If Codex should know it only when doing a particular kind of task, it is a skill. If Codex needs to reach a system outside the repository, that is MCP, and a skill can describe how to use those tools well. The decision guide walks through edge cases.

Where to get skills

Built into Codex. System skills ship with Codex. $skill-creator interviews you and drafts a new skill; $skill-installer installs skills from OpenAI’s curated list (for example $skill-installer linear) or from another GitHub repository.

Plugins. The plugin directory shared by ChatGPT and Codex holds packaged workflows, many of which include skills. In the CLI, /plugins opens the browser.

This directory. codexskills.dev is an independent catalog of free, MIT-licensed skills written for Codex. It is not affiliated with OpenAI. Every skill can be installed with one command:

curl -fsSL https://codexskills.dev/install.sh | sh -s -- systematic-debugging agents-md-authoring

That unpacks each skill into ~/.agents/skills/<name>/. Add --project to install into ./.agents/skills so the skill is committed with the repository. The install guide covers every method, including manual copies, git and Windows.

Write your own. A skill is a text file, so the fastest path to a skill that fits your team is often to write it. The first skill tutorial builds one with $skill-creator and by hand.

What to install first

If you are new to skills, start small. Three or four skills you actually use teach you more than fifty you never trigger. These are good first picks:

• systematic-debugging makes Codex reproduce a bug before it edits anything.
• agents-md-authoring writes a lean AGENTS.md for your repository.
• implementation-planning turns a vague request into a written plan with checkpoints.
• git-commit-hygiene splits a messy working tree into reviewable commits.

The Starter Pack collection bundles ten of these, and the best Codex skills guide lists more by role.