Codex skills: what they are and how to write one

What a Codex skill is

When you build with Codex, you explain some things again and again: how to check a change before it goes live, how to write the tests, what must never reach production. A skill writes one of those down once. From then on, Codex does that job your way, and you stop retyping it.

A skill is a folder. Its one required file is SKILL.md: plain text with a short header and the instructions below it. The header has two required fields. name is what you call the skill by. description tells Codex when to use it. Everything else in the folder is optional. Here is the full layout, for a skill that checks a change before it ships:

ship-check/
├── SKILL.md         required: name, description, instructions
├── scripts/         optional: code the skill can run
├── references/      optional: longer documents
├── assets/          optional: templates and other files
└── agents/
    └── openai.yaml  optional: appearance, policy, tools

Skills are cheap to keep around. An AI model can hold only so much text at once; that limit is its context window. Codex starts with a list of each skill's name, description and file path, and by default the list takes at most 2% of the context window. It reads a skill's full SKILL.md only when it decides to use that skill. The docs call this progressive disclosure.

Where Codex finds skills

Where you save a skill decides who gets it. Codex looks in four places:

So a repo skill can serve the whole project, or only the folder you work in. There is nothing to register: save the folder, and Codex finds it and notices your edits. If a change doesn't show up, restart Codex.

Looking for .codex/skills? That was the folder when skills launched: OpenAI's changelog for 19 December 2025 puts your own skills in ~/.codex/skills and a project's in .codex/skills in the repo. Today's docs name .agents/skills instead, and don't say whether Codex still reads the old folder, so move your skills. The .codex folder itself stays: Codex keeps its settings there, such as config.toml.

How to call a skill in the Codex CLI, the IDE extension and the app

There are two ways.

• You ask. In the Codex CLI or the IDE extension, type $ and the skill's name, like $ship-check, or run /skills and pick one. In the ChatGPT desktop app, type $ in the message box; your skills also show up when you type /.
• Codex picks it. When your task matches a skill's description, Codex can use the skill without being asked. This is called implicit use.

Implicit use is what makes skills feel automatic: you ask "is this ready to ship?" and the checks run. But a skill that deploys, deletes data or emails your customers should never start by itself. For those, add agents/openai.yaml to the skill's folder:

policy:
  allow_implicit_invocation: false

The default is true. With false, Codex won't pick the skill on its own, but calling it with $ still works.

The default skills that come with Codex

Some skills are built into Codex, so you can use them on day one. OpenAI calls them system skills. They are on by default, and the docs name two:

• skill-creator writes a new skill with you. You describe the job, it asks a few questions and drafts the first version.
• skill-installer adds ready-made skills. $skill-installer linear puts OpenAI's curated linear skill into your own setup. It can also fetch a skill from another repository. Read that skill first: Codex will follow what it says.

Run /skills in the Codex CLI to browse the skills you have. To switch the built-in ones off for one project, add this to the project's .codex/config.toml and restart Codex:

[skills.bundled]
enabled = false

Codex reads that file only in projects you trust.

How to write a small skill

The quickest way is to let Codex write it. Type $skill-creator, a skill that comes with Codex. It asks you what the skill should do, when it should run, and whether plain instructions are enough or it needs scripts.

Writing one by hand is simple too. Save this as .agents/skills/ship-check/SKILL.md in your repo:

---
name: ship-check
description: Check a change before it ships. Use when the user asks to ship, release, deploy or merge. Do not use for drafts or experiments.
---

# Ship check

1. Run the tests. If any fail, stop and list them.
2. Look through the changed files for passwords, keys and tokens.
   If you find one, stop and say where it is.
3. Write a short note in plain words: what changes for users,
   what could break, and how to undo it.
4. Ask me before anything goes to production.

What makes it work:

• The description says when, and when not. Codex matches your task against it. Put the trigger words first: when the list of skills gets too long, Codex shortens the descriptions to fit.
• Every step has a clear end. "Run the tests" can be checked. "Make sure it's good" can't.
• One job per skill, as OpenAI advises. A release check and a design guide are two skills.
• Instructions before code. Add scripts/ only when a step must run exactly the same way every time.

Then test the trigger: ask for the job in other words, like "can this go live?", and check that Codex picks the skill. If it doesn't, fix the description, not the steps.

AGENTS.md or a skill?

Both are plain instructions. What differs is when Codex reads them, and that decides what goes where.

Codex reads AGENTS.md at the start of every run: the file in ~/.codex, then at most one per folder from the repo root down to where you work. By default it stops adding files once they reach 32 KiB together, about 32,000 characters of plain English. You can raise the limit with project_doc_max_bytes in ~/.codex/config.toml, but then every run carries the extra text.

My rule: if Codex needs it in every task, it goes in AGENTS.md. How to work, the commands, what must never happen. If only some tasks need it, like a release, the test setup or a security review, it becomes a skill. For what the short rules should say, most of my CLAUDE.md guide applies to AGENTS.md as well.

The paths, limits and settings in this guide are from OpenAI's Codex docs on skills, slash commands, configuration and AGENTS.md, and from its changelog, all checked on 10 November 2026.

Add the MVP System Design playbook to Codex

I made my free MVP System Design playbook in exactly this shape. The agent rules, agent-rules.md, are about 6 KB and go in your AGENTS.md. The skill holds 16 chapters, from system design to rate limits. At about 85 KB, they are far past the 32 KiB default, so they live in the skill, and the rules tell Codex to read the right chapter before it works in an area. It is plain instructions for the AI, with no code to run, under the MIT license.

1. Get the playbook on the Codex playbook page. The link comes right after a short form.
2. Open your project in Codex and paste the one line from the playbook. Codex adds the playbook as a skill.
3. Copy agent-rules.md into the AGENTS.md at your repo root, or into ~/.codex/AGENTS.md for every project. Then start Codex again, so it reads the new rules.
4. Work as usual. Codex picks the skill when a task fits, or you call it with $mvp-system-design.

Mistakes to avoid

• Everything in AGENTS.md. Past 32 KiB, Codex stops adding files. It adds the files closest to your work last, so your most specific rules are the first to be dropped.
• Two skills with one name. Codex doesn't merge them, and both can show up when you pick a skill. Give each its own name.
• Secrets in a skill. Skills in the repo are committed with your code. Keys and passwords never go in them.

Questions about Codex skills

Building with Claude Code too? Read how Claude Code skills work. All guides: articles.