Codex skills: how to write, install and share them
A Codex skill is a folder with a SKILL.md file that teaches Codex one workflow. Writing one takes minutes; the parts that decide whether it helps are the description, the folder Codex reads it from, and how the rest of your team gets the current copy.
What a Codex skill is
A skill packages instructions, resources and optional scripts so Codex can follow a workflow reliably. OpenAI's guide describes it as a directory with a SKILL.md file plus optional scripts and references, and says skills build on the open Agent Skills standard. SKILL.md must include a name and a description in its front matter, followed by the instructions.
Optional folders sit beside it: scripts/ for executable code, references/ for documentation, assets/ for templates and resources, and agents/openai.yaml for appearance, invocation policy and tool dependencies. The specification limits the name to 64 lowercase letters, numbers and hyphens, matching the folder name, and the description to 1,024 characters.
Skills load progressively. Codex starts with each skill's name, description and file path, and reads the full SKILL.md only when it decides to use that skill. By default that initial list uses at most 2% of the model's context window, or 8,000 characters when the window is unknown. When many skills are installed, Codex shortens descriptions first and may leave some skills out with a warning; the skills.max_context_tokens setting raises the budget up to 10,000 tokens.
Write your first Codex skill
There are three ways to start. The built-in creator, invoked in Codex as $skill-creator, asks what the skill does, when it should trigger, and whether it should stay instruction-only or include scripts; instruction-only is the default. Record & Replay drafts a skill from a workflow you demonstrate. Or you create the folder by hand: a directory named after the skill, holding a SKILL.md whose front matter has name and description, then the steps in Markdown.
The description does most of the work. Codex can choose a skill on its own when a task matches its description, so OpenAI advises concise descriptions with clear scope and boundaries, and putting the main use case and trigger words first, so the skill still matches if Codex shortens the description. Saying when the skill should not trigger is as useful as saying when it should.
Codex detects skill changes automatically. If an edit does not show up, restart Codex.
- Keep each skill focused on one job.
- Prefer instructions over scripts unless you need deterministic behavior or external tooling.
- Write imperative steps with explicit inputs and outputs.
- Test prompts against the description to confirm the skill triggers when you expect.
Sources: OpenAI, Build skills
Where Codex looks for skills
Codex reads skills from repository, user, admin and system locations. In a repository it scans .agents/skills in every folder from the current working directory up to the repository root, so a skill can apply to one module or to the whole repository depending on where you commit it.
| Scope | Location | Use it for |
|---|---|---|
| Repository | $CWD/.agents/skills, the folder where you launch Codex | Skills for one service or module |
| Repository | $CWD/../.agents/skills, a parent folder inside the repository | Skills for a shared area of a nested repository |
| Repository | $REPO_ROOT/.agents/skills, the repository root | Skills for everyone working in the repository |
| User | $HOME/.agents/skills | Your own skills, in any repository |
| Admin | /etc/codex/skills | Default skills for every user of a machine or container |
| System | Bundled with Codex by OpenAI | Built-in skills such as skill-creator |
Codex follows symlinked skill folders, so one copy can serve several locations. If two skills share a name, Codex does not merge them, and both can appear in skill selectors. Claude Code reads .claude/skills instead, so a repository that serves both tools usually keeps one copy in .agents/skills and links it into .claude/skills.
Sources: OpenAI, Build skills; Anthropic, Extend Claude with skills
Install, use and turn off skills
To add curated skills to your own Codex setup, use the built-in installer, for example $skill-installer linear for the Linear skill. You can also ask the installer to download skills from other repositories; OpenAI publishes its curated set in the openai/skills repository. Newly installed skills are detected automatically, or after a restart.
Codex uses a skill in two ways. Explicitly, when you run /skills or type $ followed by the skill's name in the Codex CLI or the IDE extension. Implicitly, when it judges that your task matches the skill's description.
To turn a skill off without deleting it, add a [[skills.config]] entry with the skill's path and enabled = false to ~/.codex/config.toml, then restart Codex. To keep a skill available but stop Codex from picking it on its own, set allow_implicit_invocation to false under policy in agents/openai.yaml; naming it with $ still works.
ChatGPT skills: the same format in ChatGPT
OpenAI documents skills for ChatGPT and Codex in one guide, and a skill written for one works in the other. Standalone skills are available in the ChatGPT desktop app, the Codex CLI and the IDE extension. Skills bundled in plugins are also available in Chat and Work across ChatGPT on the web, desktop and mobile. In ChatGPT you type @ to select a skill, and ChatGPT can also choose one when your task matches its description.
In ChatGPT, skills live under Plugins in the sidebar, on the Skills tab, which lists skills that are installed, created by you, shared with you, and shared by your workspace. You can create one with chat, where ChatGPT uses its built-in skill-creator and asks follow-up questions, build it in the Skills editor, or upload one from your computer. Skills shared with you or your workspace are installed from the same page.
Sources: OpenAI, Build skills; OpenAI Help Center, Skills in ChatGPT
Check that a skill triggers when it should
A skill that never fires, or fires on the wrong task, is worse than none. Five checks take a few minutes in a fresh Codex session.
- Listing: run /skills and confirm the skill appears with the description you wrote.
- Explicit use: name it with $ on a real task and compare the output with the steps and format in SKILL.md.
- Implicit use: describe the same task in plain words, without naming the skill, and see whether Codex picks it.
- Negative check: send a nearby request the skill should not handle, and confirm Codex leaves it alone.
- Edit check: change one line, start a new session, and confirm the change arrived; restart Codex if it did not.
Sources: OpenAI, Build skills
What Codex skills do not do
A skill is guidance, not enforcement. Codex decides when to use it unless you name it, and a model following the same steps can still reach a different judgment. For work where the format is contractual, keep a human check at the end.
A skill can carry scripts that run with Codex's permissions. Read every file before installing someone else's skill. And a skill carries a method, not your project's history: decisions, documents and preferences are a separate problem, which our guide to Codex memory covers.