A Codex skill is a folder with a SKILL.md that Codex loads when your request matches its description, or when you type $skill-name. Commit it to .agents/skills in the repo and everyone who clones it gets it; the same file works in Claude Code from .claude/skills.
A skill is a folder with a SKILL.md file and any scripts, references or assets it needs. SKILL.md opens with frontmatter that must have a name and a description, followed by the instructions. Codex comes with $skill-creator to write one with you and $skill-installer to add curated skills from other repositories.
Where Codex looks for skills
Codex scans four scopes. Two skills with the same name both show up; they don't merge:
Repository: .agents/skills in the folder you work in and every folder above it, up to the repository root. Commit skills here to share them.
User: ~/.agents/skills, for every repository on your machine.
Admin: /etc/codex/skills, for everyone on the machine.
System: the skills OpenAI bundles with Codex.
How Codex picks a skill
Each session starts with every skill's name and description, capped at 2% of the model's context window (8,000 characters when the window is unknown). Codex reads a full SKILL.md only when it picks that skill, which happens two ways:
Implicitly, when your request matches the description, so write it as what the skill does and when to use it.
Explicitly, when you type $ and the skill's name or pick it from /skills in the CLI or IDE extension. In ChatGPT, type @.
One skill for Codex and Claude Code
Both tools use the Agent Skills format, so a SKILL.md with a name and a description runs in either. Codex looks in .agents/skills and Claude Code in .claude/skills: keep one copy and symlink each skill folder into the other location, since both follow symlinked skill folders. Test Claude Code-only fields, such as disable-model-invocation, in Codex before relying on them. How Claude Code chooses skills is on Claude Code skills.
Skills inside a Codex plugin
A Codex plugin bundles skills with MCP servers and hooks, installed from the plugin directory or with /plugins in the CLI; how to install, manage and publish one is on Codex plugins. Zest's Codex plugin is a small working example: in October 2026 it ships 16 skills, such as login, status, sync and standup, each a short SKILL.md that calls one tool on the plugin's local MCP server, plus two hooks that keep the Zest login fresh.
Codex skills, AGENTS.md and MCP
They split the work. Codex reads AGENTS.md on every run, from ~/.codex and then the repository root down to the folder you work in, up to 32 KiB by default, so keep it to rules that always apply. A skill loads only when picked, so a long procedure costs little until it's needed. An MCP server connects Codex to an outside tool: add one with codex mcp add <name> -- <command> or an [mcp_servers.<name>] table in config.toml.
Which Codex skills a team actually uses
On one engineer's laptop, 139 of 180 hand-started Codex sessions (77%, June 21 to September 22, 2026) opened a SKILL.md. In June an open-source skill pack drove it, its using-superpowers skill running in 55 of 62 sessions; by September the repositories' own skills had taken over, led by a Cloudflare deploy skill in 56. Codex reads a skill through the shell, so we counted SKILL.md paths in its tool calls.
Zest's Codex plugin records a skill when you invoke it with $name or /name, or when Codex reads its SKILL.md, from repository, user and plugin folders. Each engineer's skills show under Skills in the AI Stack view, next to their Claude Code skills. More in Codex usage.
TRY IT ON YOUR TEAM
See what your team ships with AI.
Starter is free (3 seats, no credit card). Pro is $49 a month with 5 seats and Max is $149 a month with 10 seats — priced per workspace, not per engineer, with extra seats at $19 a month.
Add a [[skills.config]] entry with enabled = false to ~/.codex/config.toml. The skill stays on disk, and Codex stops offering it.
What is the difference between a Codex skill and a plugin?+
A skill is one folder of instructions. A plugin packages skills with MCP servers and hooks, so a team installs the whole set in one step from the plugin directory.
Do Codex skills need to be listed in AGENTS.md?+
No. Codex lists every installed skill's name and description at the start of a session on its own. Keep AGENTS.md for rules that apply to every task.
