Codex skills.
A Codex skill is a folder with a SKILL.md file of instructions that Codex loads when a task matches its description. Codex reads skills from .agents/skills in your project and in your home folder, runs one when you type $ and its name, and picks one by itself when your task fits. Claude Code and Cursor read the same format, so one skill serves all three.
Where Codex looks for skills
| Where | Folder | Who gets it |
|---|---|---|
| The folder you start Codex in | .agents/skills/<name>/ | This project, committed with it |
| Each folder above it, up to the repository root | .agents/skills/<name>/ | Everything under that folder |
| Your home folder | ~/.agents/skills/<name>/ | Every project on your machine |
| The machine | /etc/codex/skills/<name>/ | Every user on the machine |
| Built in | Comes with Codex | Everyone, such as skill-creator |
Older posts name ~/.codex/skills; Codex's own docs now list .agents/skills. If a new skill doesn't show up, restart Codex.
How to run a skill in Codex
- Type $ and the skill's name, such as $skill-creator, in the CLI or the IDE extension.
- Run /skills to see every skill Codex has loaded and pick one.
- Or just describe the task. Codex reads every skill's description and uses the one that fits.
To keep a skill from running on its own, set allow_implicit_invocation: false in the skill's agents/openai.yaml. Typing $ and its name still works.
How to install a skill
For a skill from OpenAI's list, ask the built-in installer by name:
$skill-installer linear
For a skill from another repository, ask the installer to fetch it, or copy its folder into .agents/skills in your project, or ~/.agents/skills for every project. A skill is only a folder, so committing it to the repository gives it to everyone on the team.
Write your own
SKILL.md needs a name and a description at the top. The description is what Codex reads to decide when to use it, so say when it applies and when it doesn't:
--- name: site-design description: Our site's type, colour, layout and illustration rules. Use when building or changing any page. Not for backend code. --- - Headings and text: Mona Sans. Code: Geist Mono. - One accent colour, #1a7569, for buttons and links only. - Every section shows the product: a screenshot or an illustration.
Keep AGENTS.md for the few rules every task needs, since Codex reads it every time. Put the long, specific guidance in skills, which load only when a task calls for them.
Design skills worth adding to Codex
Codex builds pages that work, but on its own defaults they look like every other AI-built site. Design skills give it decisions to follow. Most are plain SKILL.md folders, so they work in Codex as they do in Claude Code:
| Skill | What it adds |
|---|---|
| frontend-design (Anthropic) | A clear direction for type, colour, layout and motion, away from the usual AI defaults |
| Impeccable | Commands such as polish and typeset, and a check for AI-slop patterns |
| web-design-guidelines (Vercel) | A review of your UI code for accessibility, focus and form mistakes |
| Illos | Animated illustrations in one of four themes, each checked before it lands |
All nine, with what each is best for: the best design skills compared.
Illustrations in Codex
The Illos skills draw animated SVG illustrations in Shader, HUD, Isometric or Interface, and check each one. One command adds them to Codex and every other coding agent on your machine:
npx -y illos setup
Then type $illos-isometric and describe the illustration, or ask in plain words. The skills come with Pro; the 65 free illustrations in the library need no account, and adding illustrations with your agent shows how.
Questions
Anything else? Write to hello@illos.dev.
Where are Codex skills stored?
In .agents/skills inside your project, and in ~/.agents/skills in your home folder for every project. Codex also checks each folder above where you start it, up to the repository root.
How do I use a skill in Codex?
Type $ and the skill's name, or run /skills to pick one. Codex also uses a skill by itself when your task matches its description.
What is the difference between AGENTS.md and a skill in Codex?
Codex reads AGENTS.md on every task, so it should stay short. A skill loads only when a task needs it, so it can carry long instructions, examples and scripts.
Do Claude Code skills work in Codex?
Yes, when they are plain SKILL.md folders: copy the folder into .agents/skills. A skill that relies on a tool only Claude Code has may need small changes.