What is a Codex skill?
A Codex skill is a folder with a SKILL.md file that teaches Codex how to do one task, such as writing release notes or fixing a failing CI run. The file has a short header with a name and a description, followed by instructions in Markdown. The folder can also hold scripts/, references/ and assets/.
Codex uses the same open Agent Skills format as Claude, so a skill written for Claude Code works in Codex too. OpenAI's skills documentation says standalone skills are available in the Codex CLI, the IDE extension and the ChatGPT desktop app.
Where does Codex look for skills?
Codex reads skills from .agents/skills folders, from the folder you're working in up to the repo root, plus $HOME/.agents/skills, /etc/codex/skills and its bundled system skills:
| Scope | Path | Use it for |
|---|---|---|
| Current folder | $CWD/.agents/skills |
Skills for one module or folder |
| Parent folder | $CWD/../.agents/skills |
Skills shared across part of a repo |
| Repo root | $REPO_ROOT/.agents/skills |
Skills for the whole repo |
| User | $HOME/.agents/skills |
Your personal skills, in every repo |
| Admin | /etc/codex/skills |
Machine or container wide skills |
| System | Bundled with Codex | Built-ins such as skill-creator and plan |
A few details from the docs:
- Codex follows symlinks, so a skill folder can be a link to somewhere else.
- If two skills share a
name, Codex doesn't merge them. Both can show up when you pick a skill, so give every skill a unique name. - Codex notices new and changed skills on its own. If an update doesn't appear, restart Codex.
How does Codex pick a skill?
Codex runs a skill in one of two ways: implicitly, when your request matches its description, or explicitly, when you call it by name.
- Implicitly. At startup Codex loads each skill's name, description and file path. When your request matches a description, Codex reads that skill's full
SKILL.mdand follows it. - Explicitly. In the CLI or IDE extension, type
$and the skill's name, like$release-notes, or run/skillsto choose from a list. In ChatGPT you mention a skill with@instead.
Because implicit selection depends on the description, write it for matching: say what the skill does, when to use it, and put the trigger words first. Codex keeps the startup list of skills within a budget: by default 2% of the model's context window, or 8,000 characters if the window size is unknown. When you have many skills, Codex shortens descriptions first and may leave some skills out with a warning. You can set a different budget with skills.max_context_tokens, up to 10,000 tokens.
Write your first Codex skill
- Create the folder:
~/.agents/skills/release-notes/for a personal skill, or.agents/skills/release-notes/in a repo to share it. - Add
SKILL.md:
---
name: release-notes
description: Draft release notes from merged pull requests, grouped as New,
Improved and Fixed. Use when the user asks for release notes, a changelog
or what shipped since the last tag.
---
# Release notes
1. List the pull requests merged since the last tag (git log or gh pr list).
2. Group them as New, Improved and Fixed. Skip refactors and dependency bumps.
3. Write one line per change from the user's point of view, starting with a verb.
4. Put breaking changes first, with what users must do.
If there is no tag, ask which commit or date to start from.
- Start Codex in a repo and type
$release-notes, or ask "write release notes for this week" and let Codex pick it.
You can also ask Codex to build the skill for you: type $skill-creator and describe what you want. It asks what the skill does, when it should trigger and whether it needs scripts.
For the rules on names and descriptions, see how to write a SKILL.md. If you already have a prompt that works, the free SKILL.md generator turns it into a skill file.
Optional: agents/openai.yaml
Codex reads an optional agents/openai.yaml file inside the skill folder for settings the open standard doesn't cover. It has three sections: interface (display name, icon and colors shown in the ChatGPT desktop app), policy and dependencies (tools the skill needs, such as an MCP server).
The setting most people want is turning off implicit use, so a skill only runs when you call it with $name:
# release-notes/agents/openai.yaml
policy:
allow_implicit_invocation: false
Other agents ignore this file, so adding it doesn't break the skill in Claude Code.
Install, turn off and share skills
Install a ready-made skill. Inside Codex, the built-in $skill-installer installs curated skills by name, for example $skill-installer linear, and can also fetch skills from other repositories. Restart Codex afterwards so it picks them up. Note that OpenAI's older openai/skills catalog is now marked deprecated in favor of the openai/plugins repository.
Install from any Git repo. The open source skills command installs skills from a GitHub repo into Codex's folder:
# project install, into .agents/skills
npx skills add https://github.com/<owner>/<repo>.git -a codex
# personal install, for every repo
npx skills add https://github.com/<owner>/<repo>.git -a codex -g
Turn a skill off without deleting it by adding this to ~/.codex/config.toml, then restarting Codex:
[[skills.config]]
path = "/Users/you/.agents/skills/release-notes/SKILL.md"
enabled = false
Share with a team. Commit .agents/skills/ to the repo and everyone who opens it in Codex gets the same skills. To distribute skills more widely, OpenAI recommends packaging them as a plugin, which works across Codex and ChatGPT.
Useful Codex skills to start with
You don't have to write every skill yourself. These public collections exist on GitHub today and work with Codex. As with any code you install, read a skill before you turn it on.
| Collection | What's in it | How to get it into Codex |
|---|---|---|
| Built-in system skills | skill-creator for writing new skills, plan for planning work |
Already installed |
| openai/plugins | OpenAI's official plugin catalog, with plugins for GitHub, Linear, Sentry, Vercel, Figma, Notion and more | The Plugins tab in the ChatGPT desktop app, or /plugins in the CLI |
| obra/superpowers | A popular set of development workflow skills: brainstorming, writing plans, test-driven development, systematic debugging, code review | Listed in the official Codex plugin marketplace |
| vercel-labs/agent-skills | Vercel's skills for React and Next.js performance, web design review and deploying to Vercel | npx skills add vercel-labs/agent-skills -a codex |
| trailofbits/skills | Security research and audit skills from Trail of Bits, such as differential review and static analysis | codex plugin marketplace add trailofbits/skills |
| Dimillian/Skills | One developer's Codex skills for SwiftUI and iOS work, App Store release notes, and multi-agent review and bug hunts | npx skills add Dimillian/Skills -a codex |
For a longer, Claude-focused list, see the best Claude Code skills. Most of those collections install into Codex the same way.
Share one skill between Codex and Claude Code
The format is the same; only the folder differs. Codex reads .agents/skills/ and Claude Code reads .claude/skills/. You have two simple options.
- Let the installer handle it. Point the skills command at both agents. It keeps one copy and links it into each folder, so an update reaches both:
npx skills add https://github.com/<owner>/<repo>.git -a codex -a claude-code -g
- Write portable skills. Stick to
nameanddescriptionin the header, describe actions ("run the tests") instead of naming one agent's tools, and put agent-specific settings in their own places:agents/openai.yamlfor Codex, extra header fields likedisable-model-invocationfor Claude Code. Each agent ignores the other's settings.
Skills are also different from AGENTS.md. An AGENTS.md file is always loaded for a repo and suits standing rules like "use pnpm". A skill loads only when a task needs it and suits procedures like "how we write release notes".
Keep Codex and Claude skills in one place
If you use both agents, keep the skills themselves in one Git repo instead of copying folders around. Kipt does this for you: your prompts and skills live as Markdown in a private GitHub repo you own, Promote to skill turns a saved prompt into a SKILL.md, and the whole library installs into Codex and Claude Code with one npx skills add https://github.com/<you>/<repo>.git command.