OpenAI Codex
How Agent Skills work in OpenAI Codex. Skill discovery, activation methods, directory hierarchy, configuration, the openai.yaml file, and where skills run.
For the official documentation, see Codex Skills on OpenAI's developer platform.
How Codex Uses Skills
Like other AI tools with Agent Skills, Codex uses progressive disclosure to stay efficient. When it starts, Codex loads only the metadata for each skill installed, including the name, description, and file path. The complete SKILL.md instructions are loaded only when a skill is activated.
This lets you install many skills without affecting performance.
Two Activation Methods
Users can directly reference a skill using the /skills command or $ mention. For example, typing $seo-writer activates the SEO writing skill by name.
The description field is crucial as it helps Codex find and activate your skill for the appropriate tasks.
Skill Discovery
Codex looks for skills in several locations, arranged from the most specific to the most general:
| Scope | Path | Purpose |
|---|---|---|
| Repo (local) | .agents/skills in current dir | Skills specific to the current folder |
| Repo (parent) | .agents/skills above current dir | Shared organizational skills |
| Repo (root) | $REPO_ROOT/.agents/skills | Repository-wide skills |
| User | $HOME/.agents/skills | Personal skills accessible across projects |
| Admin | /etc/codex/skills | System-wide administrative skills |
| System | Bundled with Codex | OpenAI's default skills |
Codex supports symlinked skill folders and automatically detects changes, so you can organize skills as needed.
SKILL.md in Codex
Codex follows a standard format for Agent Skills. Every skill needs a SKILL.md file with YAML frontmatter:
The name and description fields are essential. The description helps Codex determine whether to activate your skill for implicit use.
Skill Directory Structure
The openai.yaml File
Codex supports an optional agents/openai.yaml file to set up how a skill looks in the UI and declare external dependencies:
This determines how the skill appears to users — custom icons, colors, and display names.
Creating and Installing Skills
Codex has built-in helpers for working with skills:
| Helper | Purpose |
|---|---|
$skill-creator | Guides you through creating a new skill interactively. It sets up the directory structure, writes the SKILL.md, and configures optional files. |
$skill-installer | Downloads and installs skills from external repositories beyond the built-in ones. |
To create a skill manually, you need a folder with a SKILL.md file that includes the required frontmatter.
Configuration
You can disable specific skills in your Codex config file at ~/.codex/config.toml:
This is useful if you've installed a skill but want to prevent Codex from using it temporarily without deleting the files.
Tips for Codex-Specific Skills
Selling Codex Skills on Skly
When creating skills for the Skly marketplace that work with OpenAI Codex:
- List "Codex" as a supported AI tool so buyers can find Codex-compatible skills.
- Follow the Agent Skills format — Codex requires
SKILL.mdwith proper YAML frontmatter. - Include the openai.yaml file if your skill can benefit from custom branding or needs to declare tool dependencies.
- Test both activation methods — ensure your skill works with explicit
$mentions and implicit discovery. - Bundle reference files — Codex only loads what it needs, so comprehensive documentation has no extra cost.