OpenAI Codex CLI Adds Discoverable Skills System Behind Flag

OpenAI’s Codex CLI adds a skills system, currently behind a flag

OpenAI’s Codex CLI now includes a skills system that can be enabled with codex --enable skills. Skills are discovered from project documentation and from any directory under ~/.codex/skills/ that contains a SKILL.md file. The runtime injects skill metadata into the system prompt, making available skills visible to the model during a session.

How discovery works and where skills live

• Project docs and a runtime “## Skills” section can list additional skills that Codex will consider at runtime.
• Codex also reads any directory tree under ~/.codex/skills/ and treats directories that include SKILL.md as skills.
• OpenAI ships some built-in global skills under ~/.codex/skills/.system, including a plan skill and a skill-creator skill. Custom global skills can be dropped into ~/.codex/skills/ as well.
• Because the system uses the system prompt and simple file reads rather than bespoke skill tool hooks, arbitrary directory layouts under the skills tree work so long as a SKILL.md is present.

This approach differs from systems that only read plugin subdirectories or a single skills folder; Codex pulls a list of skills into the system prompt at startup and uses that list as the source of truth.

The “Discovery” meta-skill: rules and behavior

The built-in Discovery guidance defines how skills are selected and used. Key points:

• Triggering: If a skill is named (for example with $SkillName) or the task clearly matches a skill’s description, that skill must be used for that turn. Multiple mentions mean multiple skills should be used. Skills are not carried across turns unless re-mentioned.
• Missing or unreadable skills: If a named skill is not present or its path can’t be read, state that briefly and continue with the best fallback.
• Progressive disclosure when using a skill:
  1. Open the skill’s SKILL.md and read only what’s needed to follow the workflow.
  2. If SKILL.md points to extra folders (for example references/), load only the specific files needed; avoid bulk-loading.
  3. If scripts/ exist, prefer running or patching them rather than retyping large code blocks.
  4. Reuse assets/ or templates instead of recreating from scratch.
• Coordination and sequencing: When multiple skills apply, pick the minimal set that covers the request, state the order, and announce which skills will be used and why.
• Context hygiene and safety: Keep context small by summarizing long sections, avoid deep nested references, pick only relevant variant files, and if a skill can’t be applied cleanly, state the issue and proceed with a fallback.

The Discovery guidance emphasizes the YAML description in SKILL.md as the primary trigger signal and recommends brief clarifications if applicability is unclear.

What this means for workflows

The new system makes it straightforward to add reusable, on-disk skill definitions that Codex can discover from both local project documentation and a user skills directory. The combination of system-prompt injection, selective file reads, and the Discovery rules creates a predictable set of behaviors for invoking, sequencing, and falling back from skills.

Read the original post: OpenAI’s Codex CLI now offers a new skills system