A Codex skill is a folder containing a SKILL.md file, a short set of written instructions with a name and a description, plus any optional scripts or reference files, which Codex follows whenever a task matches it. You write the process once, and Codex uses it every time that kind of job comes up, either because you call it by name or because it recognises the task from the description.
Think weekly update, campaign brief or meeting follow-up: OpenAI's own docs suggest those as good first skills. This page is the Codex side, meaning folders and files on your computer. For skills inside ChatGPT itself, see how skills work in ChatGPT.
What goes inside a skill folder
The only required file is SKILL.md, and it must include two fields: name and description. Everything else is optional, such as scripts, templates, examples or brand guidance. Skills follow the open agent skills standard. A minimal SKILL.md has a short header with the name and description, then the instructions underneath. In plain text it looks like this:
A tiny SKILL.md
name: weekly-update
description: Use when asked for the weekly team update. Not for client reports.
Pull this week's finished tasks, group them by project, and write three short paragraphs in plain English.
In the real file, the name and description sit between two lines of three hyphens at the top. The instructions below them are just plain writing. You don't need to code to write a useful skill.
Where Codex finds skills on your computer
Codex reads skills from repository, user, admin and system locations. Here's OpenAI's table, in plain words:
| Scope | Where it lives | Who it's for |
|---|---|---|
| REPO | An .agents/skills folder in the current working directory, where you launch Codex | Skills for one working folder, such as a single module or service |
| REPO | An .agents/skills folder one level up, inside a Git repository | Skills for a shared area in a parent folder |
| REPO | An .agents/skills folder at the repository root | Skills for everyone using the repository, from any subfolder |
| USER | An .agents/skills folder in your home folder | Your personal skills, in any repository you work in |
| ADMIN | The /etc/codex/skills folder on the machine | Default skills for every user on a machine or container, and automation |
| SYSTEM | Bundled with Codex by OpenAI | Broad skills for everyone, such as the skill creator and plan skills |
If two skills share a name, Codex doesn't merge them; both can show up in the picker, which gets confusing fast. Codex spots skill changes automatically, and if an update doesn't appear, restart Codex. Standalone skills work in the ChatGPT desktop app, where Skills sits in the sidebar, as well as the Codex CLI and the IDE extension. There's more on the app in my ChatGPT desktop app guide.
Called by name, or chosen for you
Skills start in two ways. Explicitly: in the Codex CLI or IDE extension, run /skills, or type the dollar sign followed by the skill's name. Implicitly: Codex chooses a skill itself when your request matches its description.
That second route is why the description matters more than anything else in the file. OpenAI's advice is to write concise descriptions with clear scope and boundaries, and to front-load the key use case and trigger words. If you never want Codex to pick a skill on its own, an optional agents/openai.yaml file can set allow_implicit_invocation to false; calling the skill by name still works.
Building your first one
There are three routes, and the first two need no file editing at all:
- Show it. Record and Replay captures a workflow while you do it, inspects the steps and drafts a reusable skill from the demonstration.
- Describe it. Ask the built-in skill creator, called skill-creator, by mentioning it with the dollar sign in Codex. It asks what the skill does, when it should trigger, and whether it should stay instruction-only or include scripts. Instruction-only is the default.
- Write it. Create a folder with a SKILL.md file in one of the locations in the table above.
OpenAI's best practices are short and worth following: keep each skill to one job, prefer instructions over scripts unless you need exactly the same behaviour every time, write imperative steps with clear inputs and outputs, and test real prompts against the description to check it triggers when it should. Once a skill exists, these Codex prompts are a handy way to put it through its paces.
Why too many skills backfires
This is the catch most guides miss. Codex doesn't load every skill in full. It starts with a list of each skill's name, description and file path, and only reads the whole SKILL.md once it decides to use one. That starting list has a budget: by default it uses at most two percent of the model's context window, or 8,000 characters when the window size is unknown.
Want AI doing the heavy lifting in your marketing?
I build the systems that handle the boring 80 percent, so you get your week back. Done properly, with the human kept in.
Install a lot of skills and Codex shortens the descriptions first. With large sets it may leave some skills out of the list entirely and show a warning. A vague description that gets trimmed can stop a skill being chosen at all. You can raise the budget with a setting called skills.max_context_tokens, up to 10,000 tokens, but the better fix is fewer, sharper skills.
To switch a skill off without deleting it, add a skills config entry to the config.toml file in the .codex folder in your home folder, pointing at that skill's SKILL.md, with enabled set to false. Then restart Codex.
When a skill should become a plugin
OpenAI draws a clean line: skills are the authoring format, plugins are how you share them. Direct skill folders are best for your own use and for workflows tied to one repository. If you want to hand a skill to other people, bundle two or more together, or ship one alongside a connector, package it as a plugin. Plugins work in Chat and Work across ChatGPT on the web, desktop and mobile, as well as in Codex.
There's also an installer skill, skill-installer, for pulling curated skills into your own Codex, and the docs use a Linear skill as the example. OpenAI positions it for local setup and experiments. Skills are instructions the model follows, and some can run scripts, so I'd read any SKILL.md you didn't write before you trust it.
My verdict: I'd start with one skill for a task you repeat weekly, and skip scripts until the plain instructions work. Get the description right, check it triggers, then build the next one.
If you'd like your team to capture its best process once so the AI follows it every time, that's the kind of AI enablement I help with. I run AI training and workshops for teams, and help businesses with AI enablement and workflow automation, so the busywork runs itself and people get time back. Most of that work is with SaaS marketing teams and small businesses. Here's how we can work together.
Frequently asked questions
What is a skill in Codex?
It's a folder with a SKILL.md file that holds a name, a description and instructions, plus optional scripts and reference files. Codex follows it when a task matches.
Where do I put Codex skills?
Personal skills go in the .agents/skills folder in your home folder. Team skills go in an .agents/skills folder inside the repository, often at the root.
How does Codex decide to use a skill?
Either you name it, with /skills or a dollar-sign mention in the CLI or IDE extension, or Codex picks it because your request matches the skill's description.
Is there a limit on how many skills Codex can use?
The starting skills list is budgeted at two percent of the context window by default, or 8,000 characters. With many skills, Codex shortens descriptions and may leave some out with a warning.
What's the difference between a skill and a plugin?
A skill is the authoring format for one reusable workflow. A plugin is the installable package for sharing skills, often with connectors, across ChatGPT and Codex.
