In December 2025, OpenAI shipped Codex Skills. The launch page led with one load-bearing sentence: Codex skills follow the agentskills.io open standard. The same one Anthropic released earlier that month. The same one Cursor, Amp, Goose, Roo Code, Gemini CLI, and roughly thirty other coding agents have since adopted.
What that means in practice: a Codex skill is a SKILL.md folder. A Claude skill is a SKILL.md folder. The folders are interchangeable.
If you author one, you have authored both.
This article covers what a Codex skill is on disk, how Codex finds it, how you invoke it, and where the catalog lives at github.com/openai/skills. It also answers the question Claude Code users keep asking in private: does my existing skill folder run in Codex without changes? Short answer, yes. Long answer below.
What a Codex skill is, mechanically
A skill is a directory with one required file, SKILL.md. That file has YAML frontmatter at the top with two required fields, name and description, followed by Markdown instructions in the body. Everything else is optional.
Here is the verbatim frontmatter from gh-address-comments in OpenAI's catalog:
---
name: gh-address-comments
description: Help address review/issue comments on the open GitHub PR for the current branch using gh CLI; verify gh auth first and prompt the user to authenticate if not logged in.
metadata:
short-description: Address comments in a GitHub PR review
---
The whole format fits in five lines. The frontmatter tells Codex what the skill is called and when it should fire. The body tells the agent what to do once it has fired. That body can be a checklist, a recipe, a set of conventions, a multi-step procedure. Codex pulls the full body into context only when the skill activates, so a 400-line procedural skill costs roughly the description's length when idle. The agentskills.io spec calls this progressive disclosure and caps descriptions at 1,024 characters.
A skill folder usually looks like this:
my-skill/
├── SKILL.md # required: frontmatter + body
├── scripts/ # optional: code the agent can run
├── references/ # optional: docs loaded on demand
├── assets/ # optional: templates, schemas, images
└── agents/openai.yaml # optional: Codex UI metadata
The scripts/, references/, and assets/ directories are part of the open spec. The agents/openai.yaml file is the one Codex-specific touch, an optional UI manifest that controls how the skill renders in the Codex app's Plugin Directory. Strip it out and the skill is a vanilla agentskills.io artifact.
Where Codex looks for skills on disk
Codex scans four scopes, in order of precedence:
- Project:
.agents/skills/<slug>/walking up from the current working directory to the repo root - User:
$HOME/.agents/skills/<slug>/ - Admin:
/etc/codex/skills/<slug>/ - System: bundled with Codex by OpenAI
Notice the user-scope path. It is ~/.agents/skills, not ~/.codex/skills. OpenAI chose the vendor-neutral .agents directory so a single folder on your machine can be shared with any agent that adopted the spec. Symlink it from ~/.claude/skills and both products see the same skills. The Codex skills docs confirm Codex follows symlinks during scanning.
That alone is the cross-tool authoring story. One folder, two products, no translation layer.
How invocation works
Two paths. Implicit and explicit.
Implicit invocation is the default. At session start Codex loads only the name and description of every available skill, roughly 2 percent of the model's context window. When your prompt's intent matches a skill's description, the agent loads the full SKILL.md body and follows it. You never type the skill's name. The model picks.
Explicit invocation uses the $skill-name syntax. Type $gh-address-comments in the Codex CLI or app and the skill fires immediately, no inference required. Use this for workflows with side effects like deploys or commits, where letting the model decide when to run feels reckless. Claude Code uses /skill-name for the same purpose. The mechanics are identical, only the sigil differs.
Codex also ships a /skills slash command that lists what is installed. The README in openai/skills shows the explicit form:
$skill-installer gh-address-comments
That runs the skill-installer skill, which lives in .system/ and ships with Codex. Skills installing skills. The bootstrap is recursive in a way that is pleasant to use.
The openai/skills repository
The official catalog lives at github.com/openai/skills. As of May 2026 it carries 19,100 stars and three categories of skill, all under skills/:
.system/ships with Codex automatically. Containsimagegen,openai-docs,plugin-creator,skill-creator, andskill-installer..curated/is OpenAI-reviewed and installable by name. Roughly forty skills covering deploy targets, observability, design tools, and language frameworks..experimental/is the community contribution path, installable by folder name or GitHub URL via$skill-installer.
Read the README carefully and you will notice something. The skill-creator skill is itself a Codex skill that helps you author new Codex skills. That is the in-product no-code path: ask Codex "create a new skill that does X" and the bundled creator interviews you, fills out the frontmatter, drafts the body, and writes the folder. It works. It is also a short interview compared to what a dedicated authoring tool can do, which is why separate tools like Knack exist to drive the interview from the user's side rather than the agent's. The output is plain agentskills.io, same folder layout, same frontmatter, no proprietary wrapper. There is a longer piece on how the no-code authoring flow works for Claude; the workflow is identical for Codex since the format is identical.
What to install today
Three skills from .curated/ that are worth pulling on day one, plus one to be aware of.
gh-address-comments turns "respond to my PR review comments" into a structured workflow. It fetches review threads with gh pr view --comments, numbers them, summarizes what each one needs, asks you which to address, then implements and commits the fixes. The kind of small-but-real procedure you stop doing in your head once it is encoded.
render-deploy generates a render.yaml Blueprint, runs through Render's MCP tools, and produces working deploys without back-and-forth. Its description reads:
---
name: render-deploy
description: Deploy applications to Render by analyzing codebases, generating render.yaml Blueprints, and providing Dashboard deeplinks. Use when the user wants to deploy, host, publish, or set up their application on Render's cloud platform.
---
A good template for your own skills. It tells the model both what the skill does and the trigger phrases that should fire it.
pdf handles "read this PDF" and "generate a PDF report" with real tooling: pdfplumber, reportlab, pypdf, and Poppler for visual checks. PDFs are the canonical task that LLMs handle badly without procedural scaffolding, and this skill is the scaffolding.
sentry wraps the Sentry CLI for read-only error inspection. Useful for the "what broke in production overnight" debugging session nobody enjoys.
The full list runs longer, with skills for Figma, Playwright, Linear, Notion, Cloudflare, Netlify, Vercel, Jupyter, ASP.NET Core, WinUI, and a one-shot migrate-to-codex skill that converts Claude Code configuration into Codex equivalents. If you are coming from Claude Code, run that migration once and your .claude/ setup arrives in .codex/ and .agents/ mostly intact.
The cross-vendor story is the real story
Pull a Claude skill out of ~/.claude/skills/ and move it to ~/.agents/skills/. Codex picks it up next session. Move it back. Claude picks it up. Nothing changes inside the folder. The body is Markdown. The frontmatter is YAML with two required keys. The supporting files are optional and follow conventions any agent reads.
The Claude side of the story is documented at code.claude.com/docs/en/skills and the public catalog is at github.com/anthropics/skills. Compare any skill from there with any skill from the openai/skills catalog and you find the same artifact with a different vendor sticker. Claude Code adds a few extension fields like context: fork (run the skill in a subagent), disable-model-invocation, and inline shell injection via !`command`. Codex does not honor those fields but does not break on them either. A skill written with extension fields runs in Codex, just without the extensions. A skill written to the open spec runs everywhere.
This is the point at which "Codex Skills" stops being a distinct product and becomes a vendor's view of one shared artifact. The right mental model is "agent skills with Codex-flavored discovery."
Author for the spec. Ship to the catalog. Let vendor adapters handle the rest.
A note for the Claude Code crowd
If your team has been writing .claude/skills/ folders for the last six months, the question is not whether they work in Codex. They do.
The question is whether you want to move them. Three options:
Keep them in .claude/skills/ and use Codex's migrate-to-codex skill to mirror them into .agents/skills/ on demand. Fine for teams primarily on Claude Code with occasional Codex sessions.
Move them to .agents/skills/ and symlink .claude/skills/ to point there. Both agents see the same files. Edits propagate. The right answer for most teams.
Publish them. A skill that solves your codebase's problem probably solves someone else's. Both openai/skills and anthropics/skills accept community contributions, and the marketplaces tracked in our piece on where Claude skills get distributed overlap heavily with the Codex side.
Staying in .claude/skills/ exclusively locks you out of Codex's plugin system, which bundles skills with MCP servers and app connectors. Plugins shipped in March 2026 and add real value at the team-distribution layer. Worth the move.
Authoring without writing code
If you read this far and your reaction is "great, now I have to write the YAML," there is a no-code path. Knack interviews you about what the skill should do, what it should not do, what failure modes to handle, what tools to call, and what the final output looks like. It writes a SKILL.md folder in the agentskills.io standard. The folder runs in Codex at .agents/skills/<slug>/, in Claude Code at .claude/skills/<slug>/, in Cursor, in Amp, in any agent that adopted the spec. There is a longer worked example at /blog/claude-skill-examples cataloging fifteen real skills people have shipped through this workflow.
That is the practical use of the open standard. One interview. One folder. Every agent.
Where this lands
Codex Skills is the same artifact as Claude Skills with a different vendor sticker on the box. The disk paths differ. The invocation sigil differs. The catalog URL differs. The format is identical down to the frontmatter keys and validation rules.
That compounds in concrete ways. A procedural skill you author for one agent carries to every other agent your team might adopt later. A skill written for Codex today runs in Cursor next month. The market has many front doors and one back room. A no-code author and a senior engineer end up writing the same artifact, and the artifact runs the same way.
Author against the spec. Your skills outlive the tool you wrote them in.