Codex skills: how to create and use skills in OpenAI Codex
Zihua Li · · 9 min read
Codex skills turn a workflow you keep explaining into a folder Codex can find and follow on its own: a SKILL.md with instructions, plus any scripts, templates or reference docs the job needs.
Codex skills are folders with a SKILL.md file that give OpenAI Codex a reusable workflow. Codex loads skills from .agents/skills in your repository and $HOME/.agents/skills, picks one on its own when a task matches the skill’s description, and runs one on request when you type $ and its name or choose it from /skills. They work in the Codex CLI, the IDE extension and the Codex app.
What a Codex skill is
A skill is a directory. The only required file is SKILL.md: YAML frontmatter with a name and a description, then Markdown instructions. Everything else is optional and is there for the instructions to point at.
pr-description/
├── SKILL.md required: name, description, instructions
├── scripts/ optional: code Codex can run
├── references/ optional: docs Codex reads when it needs them
├── assets/ optional: templates and other files
└── agents/
└── openai.yaml optional: UI metadata, invocation policy, tool dependenciesThe format is the open Agent Skills standard, which is why a skill written for Codex also runs in Claude Code, Cursor and other agents that read it. The one Codex-specific piece is agents/openai.yaml, covered below.
What makes skills cheap to keep around is progressive disclosure. At the start of a session Codex sees only each skill’s name, description and file path. It reads the full SKILL.md when it decides to use one, and reads a reference file or runs a script only when the instructions call for it. That initial list is capped at 2% of the model’s context window (8,000 characters if the window size is unknown); past that, Codex trims descriptions and may drop skills from the list with a warning. You can raise the budget with skills.max_context_tokens, up to 10,000 tokens, but a pile of overlapping skills is usually the better thing to fix.
Skills work in the Codex CLI, the IDE extension and the Codex app (Codex in the ChatGPT desktop app), where Skills in the sidebar lists the skills across your projects. Skills packaged inside a plugin also reach ChatGPT on the web and mobile.
Where Codex finds skills: .agents/skills and the rest
Codex reads skills from five kinds of location. For repository skills it walks up the tree: every .agents/skills folder from the directory you started Codex in up to the repository root counts.
| Scope | Location | Use it for |
|---|---|---|
| Repo | .agents/skills in the folder where you start Codex | Skills for one service or module |
| Repo | .agents/skills in each parent folder, up to the repository root | Skills for a shared area, or for the whole repository at the root |
| User | $HOME/.agents/skills | Your own skills, in every repository you open |
| Admin | /etc/codex/skills | Defaults for every user on a machine or container |
| System | Bundled with Codex | skill-creator and skill-installer, on by default |
The walk-up matters in a monorepo. Start Codex in services/billing and it sees the billing team’s skills in services/billing/.agents/skills as well as the repository-wide ones at the root; start it at the root and the billing skills stay out of the list. Put skills where the work they describe happens.
Two details save debugging time. Codex follows symlinks, so a link from .claude/skills to .agents/skills lets Claude Code and Codex share one copy. And when two skills have the same name, Codex doesn’t merge them or pick a winner; both can appear in the selector. Give a personal variant of a team skill its own name so it’s clear which one you are running.
Explicit and implicit invocation: $skill and /skills
There are two ways a skill gets used.
- Explicit. Type
$in the composer and pick a skill, or type its full name. In the CLI and IDE extension,/skillsopens a list to choose from. Anything after the name is part of your request, so you can steer one run. - Implicit. Codex compares your request with every skill’s description and loads a skill when one matches. You ask for “a PR description for this branch” and the
pr-descriptionskill runs without being named.
Implicit invocation lives or dies on the description. Put the job and its trigger words in the first sentence, since Codex shortens long descriptions first when space runs out, and say what the skill isn’t for when there is a neighbor it could be confused with. “Use when asked to write a PR description. Not for commit messages” prevents more misfires than a longer paragraph about what a great description looks like.
Some skills shouldn’t run just because a request sounds similar: a deploy, a release, a data backfill. For those, add agents/openai.yaml and turn implicit invocation off. $skill-name keeps working.
interface:
display_name: "PR description"
short_description: "Draft a PR body from the branch diff"
policy:
allow_implicit_invocation: falseThe same file can declare tool dependencies, such as an MCP server the skill needs, and set the icon and display name the Codex app shows.
How to create a Codex skill, step by step
The quickest start is the built-in creator: type $skill-creator, describe the workflow, and it asks when the skill should trigger and whether it needs scripts before writing the folder. Writing one by hand takes a few minutes and teaches you what the creator produces, so here is a complete one: a skill that drafts pull request descriptions the same way every time.
1. Create the folder
The folder name is the skill name: lowercase letters, numbers and single hyphens, up to 64 characters, and the name field must match it.
mkdir -p .agents/skills/pr-description/references
$EDITOR .agents/skills/pr-description/SKILL.md
$EDITOR .agents/skills/pr-description/references/template.md2. Write SKILL.md
---
name: pr-description
description: Write a pull request description for the current branch from its
diff against main. Use when asked to write, draft or update a PR description,
PR body or pull request summary. Not for commit messages.
---
# Write a pull request description
1. Run `git log --oneline main..HEAD` and `git diff --stat main...HEAD`
to see what the branch contains. Read the full diff with
`git diff main...HEAD` for any file whose purpose isn't clear from
its name.
2. Fill in references/template.md. Keep every heading; write "None"
under a heading that doesn't apply.
3. Summary: one or two sentences on what changes for a user or a
caller, not a list of files.
4. Testing: list only what was actually run on this branch. If you
can't tell, write "Not run" and say what should be.
5. Risk: name migrations, config changes, new dependencies and any
change to a public API. These are what a reviewer looks for first.
6. Print the description in a Markdown code block. Don't create or
edit the pull request unless asked.A few choices in there carry most of the weight. The steps are imperative and numbered, with the exact commands, because Codex follows a procedure more reliably than it infers one from advice. Step 4 tells it what to do when it doesn’t know, which keeps “Tests pass” out of descriptions for branches nobody tested. Step 6 draws a boundary so a request for a draft doesn’t turn into a pushed pull request.
3. Add the template
references/template.md holds the headings your team uses. Keeping it in a separate file means changing the template doesn’t touch the instructions, and Codex only reads it when the skill runs.
## Summary
## Changes
## Testing
## Risk
## Related issues4. Run it both ways
Codex detects new and edited skills automatically; if one doesn’t appear, restart the session. Call it explicitly first:
$pr-description
$pr-description the reviewers are on the payments team, call out anything touching refundsThen test the description: in a fresh session, ask for “a PR body for this branch” without naming the skill, and ask for a commit message to check that it stays out of the way. If it fires on the wrong request or misses the right one, the fix is almost always the description, not the instructions.
5. Commit it
Commit .agents/skills with the code. Everyone who opens the repository gets the skill, changes to it go through review like any other file, and the skill’s history sits next to the code it describes. When a skill should travel beyond one repository, or ship with a connector, OpenAI’s recommended package is a plugin, which bundles one or more skills for installation in Codex and ChatGPT.
A Codex skill is a folder in .agents/skills with a SKILL.md that names the skill, describes when to use it and lists the steps. Codex reads only the name and description until a task matches, then loads the instructions, so a well-described skill costs almost nothing until the moment it is needed.
Built-in skills and the skill installer
Codex ships with system skills that are on by default. The two the docs name are $skill-creator, used above, and $skill-installer, which downloads skills into your local setup:
$skill-installer linear
$skill-installer install https://github.com/<owner>/<repo>/tree/main/skills/<skill-name>Given a bare name, the installer looks in the curated list in the openai/skills repository; given a GitHub URL, it installs from any repository. That repository’s README now marks it deprecated and points to OpenAI’s plugins repository for current examples, so treat its curated folder as a catalog to borrow from rather than a list that will keep growing. Its curated skills include gh-fix-ci for failing GitHub Actions runs, gh-address-comments for working through pull request review comments, yeet for staging, committing and opening a pull request, and security-threat-model.
Installing across several agents at once is a job for the open-source skills CLI, which writes to .agents/skills and records what it installed in a lockfile. Our npx skills guide covers add, list, update and remove. For a longer list of skills worth installing, most of which run in Codex unchanged, see the best Claude Code skills.
To switch a skill off without deleting it, add an entry to ~/.codex/config.toml. A path matches one SKILL.md; a name matches every skill with that name. To turn off all bundled system skills for a project, set enabled = false under [skills.bundled] in its trusted .codex/config.toml. Restart Codex after either change.
# ~/.codex/config.toml
[[skills.config]]
path = "/Users/you/.agents/skills/old-release/SKILL.md"
enabled = falseSkills vs AGENTS.md vs custom prompts
Codex has three places to put instructions, and the line between them is about when the instructions should apply.
- AGENTS.md is read before every task. It holds what is always true in the repository: build and test commands, conventions, directories to leave alone. OpenAI’s advice is to keep it small, because every line costs context in every session.
- Skills hold procedures that matter some of the time: drafting a PR description, cutting a release, adding a migration. Only their descriptions are loaded until they are needed, so ten skills cost less than ten sections of AGENTS.md.
- Custom prompts, Markdown files in
~/.codex/prompts/run as/prompts:name, are deprecated. They only run when called, live in your home directory where teammates can’t see them, and are single Markdown files with no folder for scripts or reference docs. Any prompt you still use there moves into a skill by putting its text below anameanddescription.
A useful test: if you would want the instruction followed even when nobody mentioned the topic, it belongs in AGENTS.md. If it is a sequence of steps for one kind of task, it is a skill. Moving a long how-to section out of AGENTS.md into a skill is one of the easier ways to make every session start lighter.
Skills for code review
Review is a natural fit for a skill, because the procedure is fixed and the details are yours: which directories hold access control, which helpers must be called, what counts as Critical. A review skill run with $ before you push catches the problems you already know to look for. Codex’s own /review command and its GitHub reviewer are covered in the Codex code review guide.
The same folder works after the push. HeyDeer, an AI code review agent for GitHub pull requests, reads Agent Skills from .agents/skills: a repository check names the skills it needs, and HeyDeer follows them while it reviews each pull request. A skill your team wrote for Codex, such as how to verify a route’s access control, becomes part of every review without being rewritten.
Skills in .agents/skills serve more than one tool. Codex reads them when you work, Cursor and other Agent Skills tools read the same folder, and HeyDeer follows the ones a repository check names when it reviews a pull request, so a procedure written once is applied while code is written and again before it merges.
HeyDeer also publishes free skills that install into Codex, such as ci-audit, which measures your GitHub Actions runs and fixes what you pick. The full set is on the skills page.
Sources
Frequently asked questions
What are Codex skills?
Codex skills are reusable workflows packaged as a folder with a SKILL.md file, which holds a name, a description and instructions, plus optional scripts, references and assets. Codex sees each skill’s name and description up front and reads the full instructions only when it uses the skill. They follow the open Agent Skills standard.
Where do I put Codex skills?
Codex skills go in .agents/skills/<skill-name>/SKILL.md. Codex scans .agents/skills in the folder where you start it and every parent folder up to the repository root, plus $HOME/.agents/skills for personal skills and /etc/codex/skills for machine-wide ones. Skills bundled with Codex, such as skill-creator, load automatically.
How do I use a skill in Codex?
A skill in Codex runs when you type $ followed by its name, such as $pr-description, or pick it from the /skills menu in the CLI or IDE extension. Codex also uses a skill without being asked when your request matches the skill’s description, unless the skill’s agents/openai.yaml sets allow_implicit_invocation to false.
How do I create a Codex skill?
A Codex skill is created by making a folder in .agents/skills with a SKILL.md that starts with name and description frontmatter, followed by the instructions. The name must match the folder name. You can also type $skill-creator in Codex and describe the workflow; it asks when the skill should trigger and writes the files.
Do Codex skills work with Claude Code and Cursor?
Codex skills use the open Agent Skills format, so the same SKILL.md works in other agents that support it. Cursor reads .agents/skills directly. Claude Code reads .claude/skills, so a symlink from .claude/skills to .agents/skills lets both use one copy. Codex-only metadata in agents/openai.yaml is ignored elsewhere.
What replaced custom prompts in Codex?
Skills replaced custom prompts in Codex. OpenAI marks custom prompts in ~/.codex/prompts as deprecated; they only run when you call them as /prompts:name and live in your home directory, so they are not shared through the repository. A skill can be called explicitly, picked up automatically and committed with the code.
How many skills can Codex handle?
Codex can hold many skills, but the list it starts each session with is capped at 2% of the model’s context window, or 8,000 characters when the window size is unknown. With many skills installed, Codex shortens descriptions first and may leave some out with a warning. The skills.max_context_tokens setting raises the budget, up to 10,000 tokens.



