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.
Free for 3 seats · No credit card · One command signs in every agent on your machine
Sample data
Stack in the Zest app: how well your setup is wired, and what raises the score
USED BY ENGINEERING TEAMS AT
What a Codex skill is
A skill is a folder with a SKILL.md file, plus optional scripts/, references/ and assets/ folders. SKILL.md opens with YAML frontmatter that must have a name and a description, followed by the instructions. Run $skill-creator to write one with Codex, or $skill-installer to add curated skills.
.agents/skills/commit/SKILL.md
---
name: commit
description: Stage and commit changes in semantic groups. Use when the user wants to commit, organize commits, or clean up a branch before pushing.
---
1. Do not run `git add .`. Stage files in logical groups by purpose.
2. Group into separate commits: feat → test → docs → refactor → chore.
3. Write concise commit messages that match the change scope.
4. Keep each commit focused and reviewable.
Where Codex looks for skills
Codex scans four scopes and follows symlinked skill folders. It picks up changes on its own; if a skill doesn't appear, restart Codex. 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, such as skill-creator and skill-installer.
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). With many skills, Codex shortens the descriptions first and may leave some out with a warning. It reads a full SKILL.md only when it uses that skill:
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 @.
Only explicitly, if the skill's agents/openai.yaml sets allow_implicit_invocation: false. The same file sets the name and description the ChatGPT desktop app shows.
.agents/skills/deploy/agents/openai.yaml
interface:
display_name: "Deploy"
short_description: "Deploy the current branch to staging"
policy:
allow_implicit_invocation: false
How to turn off a Codex skill
Add a [[skills.config]] entry to ~/.codex/config.toml with the path to the skill's SKILL.md and enabled = false, then restart Codex. The skill stays on disk and Codex stops offering it. max_context_tokens under [skills] changes the skill list's budget, up to 10,000 tokens.
Codex and Claude Code both use the Agent Skills format, so a SKILL.md with a name and a description runs in either, and Cursor skills use the same format. Codex looks in .agents/skills and Claude Code in .claude/skills, and both follow symlinked skill folders: keep one copy and link it. Test Claude Code-only fields, such as disable-model-invocation, in Codex before relying on them. To copy instead, /import in the Codex CLI brings Claude Code skills and slash commands over as Codex skills. How Claude Code chooses skills is on Claude Code skills.
A plugin bundles skills with MCP servers and hooks, each skill at skills/<skill-name>/SKILL.md inside the plugin. Install one with /plugins in the CLI and its skills appear in your next session; building and publishing one is on Codex plugins. Zest's Codex plugin is a small example: 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.
Codex skills, AGENTS.md and MCP
Skills, AGENTS.md and MCP split the work. Codex reads AGENTS.md on every run: first ~/.codex/AGENTS.md (or AGENTS.override.md), then one file per folder from the repository root down to where you work, until their combined size reaches project_doc_max_bytes (32 KiB by default). 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 or a [mcp_servers.<name>] table in config.toml, and list the running ones with /mcp. A skill can declare the MCP server it needs in agents/openai.yaml, so Codex can install and wire it up.
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 in Zest with how often they ran, next to their Claude Code skills. More in Codex usage.
Stack in the Zest app: how well your setup is wired, and what raises the scoreSample data
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. See pricing
Check that the folder sits in a scanned path (.agents/skills up to the repository root, ~/.agents/skills or /etc/codex/skills) and that its SKILL.md has a name and a description. Codex reloads skills on its own; if one still doesn't appear, restart 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 a marketplace.
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.
Can Codex use my Claude Code skills?+
Yes. Both use the Agent Skills format: symlink each skill folder from .agents/skills into .claude/skills, or run /import in the Codex CLI to copy Claude Code skills and slash commands over as Codex skills.