I’ve been working through some testing of OpenAI’s new skills support in their codex CLI tool.

Skills are currently gated behind a feature flag. You turn them on by running codex --enable skills.

As I was trying to debug why a skill I’d installed wasn’t triggering, Codex told me a bit about its’ "Discovery" skill.

Claude Code finds skills in the skills subdirectories of installed plugins and the skills directory of your .claude directory at startup. It then shoves those into the system prompt as a list of available skills. At least the last time I looked, there was no way to enable specific skills for specific projects or subdirectories.

It looks like Codex is doing something very different. It allows you to list additional skills in project documentation. I think I like this?

OpenAI ship some "global" skills in ~/.codex/skills/.system - a ‘plan’ skill and a ‘skill-creator’ skill. You can drop your own global skills into ~/.codex/skills/. And because it looks like they’re just using a system prompt, the "Discovery" meta-skill, and the "File read" tool rather than custom skill tools, any sort of directory layout inside ~/.codex/skills/ works. They’re just looking for any directory in that tree with a ‘SKILL.md’ file and going from there.

This is Codex’s detailed description of what’s going on. (You can likely find the ‘real’ version of this in the publicly available source code.)

The complete “Discovery” entry I have in this chat is:

- Skill Creator: Guide for creating effective skills. This skill should be
used when users want to create a new skill (or update an existing skill)
that extends Codex's capabilities with specialized knowledge, workflows, or
tool integrations. (file: /Users/jesse/.codex/skills/.system/skill-creator/
SKILL.md)
- plan: Plan lifecycle management for Codex plans stored in $CODEX_HOME/plans
(default ~/.codex/plans). Use when a user asks to create, find, read,
update, delete, or manage plan documents for implementation work or
overview/reference documentation. (file: /Users/jesse/.codex/skills/.system/
plan/SKILL.md)
- Discovery: Available skills are listed in project docs and may also appear
in a runtime "## Skills" section (name + description + file path). These are
the sources of truth; skill bodies live on disk at the listed paths.
- Trigger rules: If the user names a skill (with $SkillName or plain text) OR
the task clearly matches a skill's description, you must use that skill for
that turn. Multiple mentions mean use them all. Do not carry skills across
turns unless re-mentioned.
- Missing/blocked: If a named skill isn't in the list or the path can't be
read, say so briefly and continue with the best fallback.
- How to use a skill (progressive disclosure):
1. After deciding to use a skill, open its SKILL.md. Read only enough to
follow the workflow.
2. If SKILL.md points to extra folders such as references/, load only the
specific files needed for the request; don't bulk-load everything.
3. If scripts/ exist, prefer running or patching them instead of retyping
large code blocks.
4. If assets/ or templates exist, reuse them instead of recreating from
scratch.
- Description as trigger: The YAML description in SKILL.md is the primary
trigger signal; rely on it to decide applicability. If unsure, ask a brief
clarification before proceeding.
- Coordination and sequencing:
- If multiple skills apply, choose the minimal set that covers the request
and state the order you'll use them.
- Announce which skill(s) you're using and why (one short line). If you
skip an obvious skill, say why.
- Context hygiene:
- Keep context small: summarize long sections instead of pasting them;
only load extra files when needed.
- Avoid deeply nested references; prefer one-hop files explicitly linked
from SKILL.md.
- When variants exist (frameworks, providers, domains), pick only the
relevant reference file(s) and note that choice.
- Safety and fallback: If a skill can't be applied cleanly (missing files,
unclear instructions), state the issue, pick the next-best approach, and
continue.