OpenAI Codex Skill Package Structure: A Complete Technical Guide

An OpenAI Codex skill package is a self-contained directory with a mandatory SKILL.md file, optional assets/, agents/, scripts/, and references/ subdirectories, and is discovered by the $skill-installer from the openai/skills repository.

The openai/skills repository defines the canonical format for bundling capabilities that the Codex runtime can discover, install, and execute without additional build steps. Understanding this structure is essential for developers building custom agents or extending the Codex ecosystem.

Top-Level Directory Layout

All skills reside under the skills/ folder and are categorized by distribution status into three protected subdirectories:

System Skills (skills/.system/)

These ship with Codex and auto-install during setup. They provide core infrastructure like the installer itself.

• skill-installer/ – Contains SKILL.md and scripts/list-skills.py for listing and installing other skills
• skill-creator/ – Utilities for scaffolding new skill packages

Curated Skills (skills/.curated/)

Public, reusable skills that users install on demand via $skill-installer. Each skill lives in its own folder (e.g., yeet/, speech/, sora/).

Experimental Skills (skills/.experimental/)

Work-in-progress prototypes using the same layout as .curated/, but hidden from default discovery unless explicitly requested.

Core Components of a Codex Skill Package

Every skill folder follows a standardized structure centered on declarative metadata and executable resources.

SKILL.md (Required)

The SKILL.md file serves as the skill's manifest and documentation. It begins with a YAML front-matter block defining:

• name – The command identifier used by Codex
• description – Human-readable capability summary
• metadata – Version, author, and dependency information

Following the front-matter, the file contains detailed markdown documentation covering prerequisites, workflow steps, and default behaviors.

Example: skills/.curated/yeet/SKILL.md defines the Git workflow automation skill, specifying how Codex should generate branch names, commits, and pull requests.

assets/ (Optional)

Static resources referenced by documentation or CLI output:

• Icons and screenshots for README rendering
• Example data files for demonstrations

Example: skills/.curated/yeet/assets/yeet.png provides the skill's visual identifier.

agents/ (Optional)

OpenAI agent configuration files in YAML format that auto-configure model-level behavior when the skill is active:

• System prompt templates
• Tool access permissions
• Model parameter overrides

Example: skills/.curated/yeet/agents/openai.yaml configures the Codex agent's behavior when executing Git workflows.

scripts/ (Optional)

Executable helper scripts, typically Python, that implement the skill's functionality:

• CLI entry points
• API integration wrappers
• Utility functions

Example: skills/.curated/speech/scripts/text_to_speech.py implements the text-to-speech conversion logic, accepting parameters like --voice and --out.

references/ (Optional)

Supplemental markdown documentation for advanced usage:

• CLI command reference manuals
• API rate limit documentation
• Prompt engineering templates

Example: skills/.curated/speech/references/cli.md documents the full command-line interface for the speech skill.

How Codex Discovers and Installs Skills

The Codex runtime uses a declarative discovery mechanism based on the $skill-installer system skill.

Discovery Process

1. Scanning: The $skill-installer reads SKILL.md files from skills/.curated/ or skills/.experimental/ in the repository
2. Parsing: It extracts the name field from each YAML front-matter block to build the skill catalog
3. Presentation: The installer displays available skills to the user with their descriptions

Installation Flow

When a user runs $skill-installer <skill-name>:

1. The installer copies the entire skill folder from the source repository (e.g., skills/.curated/yeet/)
2. It places the folder into $CODEX_HOME/skills/<skill-name> (default: ~/.codex/skills/)
3. The user receives the message: "Restart Codex to pick up new skills"

Runtime Loading

At startup, Codex scans $CODEX_HOME/skills/*/SKILL.md to:

• Load skill descriptions into the agent context
• Expose skill commands to the natural language interface
• Initialize any agent configurations from the agents/ subdirectory

Practical Examples

Listing Available Skills

To view curated skills available for installation:

$skill-installer list

This executes skills/.system/skill-installer/scripts/list-skills.py, which outputs:

Skills from openai/skills (curated):
1. yeet
2. speech
3. sora
4. ...
Which ones would you like installed?

Installing the Yeet Skill

Install the Git workflow automation skill:

$skill-installer yeet

The installer copies skills/.curated/yeet/ to ~/.codex/skills/yeet/, including its SKILL.md, assets/, and scripts/.

Using the Speech Skill CLI

Execute text-to-speech conversion using the skill's Python script:

python -m skills/.curated/speech/scripts/text_to_speech.py \
    --text "Welcome to the demo." \
    --voice cedar \
    --out output/speech/welcome.mp3

The script parameters are documented in skills/.curated/speech/references/cli.md.

Creating a GitHub PR with Yeet

Following the workflow defined in skills/.curated/yeet/SKILL.md:

# Assume you are on the main branch with changes

DESCRIPTION="fix typo in README"
git checkout -b "codex/${DESCRIPTION}"
git add -A
git commit -m "${DESCRIPTION}"
git push -u origin "$(git branch --show-current)"
GH_PROMPT_DISABLED=1 GIT_TERMINAL_PROMPT=0 gh pr create --draft --fill --head "$(git branch --show-current)"

Summary

• OpenAI Codex skill packages are self-contained directories under skills/ with a mandatory SKILL.md manifest and optional assets/, agents/, scripts/, and references/ subdirectories.
• Distribution categories organize skills into .system/ (auto-installed), .curated/ (public), and .experimental/ (prototypes).
• Discovery mechanism relies on the $skill-installer system skill parsing YAML front-matter from SKILL.md files to build installable catalogs.
• Installation process copies skill folders to $CODEX_HOME/skills/, making them available to the Codex runtime after restart.
• Practical implementations include the yeet skill for Git automation, speech for text-to-speech conversion, and sora for video generation workflows.

Frequently Asked Questions

What is the minimum required file for a Codex skill package?

A valid SKILL.md file is the only mandatory component. This file must contain a YAML front-matter block with at least a name field (the command identifier) and a description field (human-readable summary). While assets/, scripts/, and other directories enhance functionality, Codex only requires the manifest to recognize and list a skill.

How does Codex distinguish between system, curated, and experimental skills?

The runtime uses directory naming conventions within the skills/ folder. Skills in .system/ ship with Codex and auto-install during setup. Skills in .curated/ are public, reusable capabilities discoverable via $skill-installer list. Skills in .experimental/ follow the same structure as curated skills but remain hidden from default discovery unless explicitly requested by users or developers.

Where are skills installed after running the skill-installer command?

The $skill-installer command copies the skill directory from the source repository (such as skills/.curated/yeet/) into the local Codex home directory at $CODEX_HOME/skills/<skill-name>. By default, $CODEX_HOME resolves to ~/.codex/, resulting in a path like ~/.codex/skills/yeet/. Codex scans this location at startup to load available skill manifests and commands.

Can a skill package contain multiple executable scripts?

Yes, the scripts/ directory can contain any number of executable helpers, typically Python files, that implement the skill's functionality. For example, the speech skill includes scripts/text_to_speech.py for audio generation, while other skills might include separate scripts for data processing, API calls, or utility functions. The SKILL.md file documents which scripts to use for specific workflows, and the references/ directory can provide detailed CLI documentation for complex script interfaces.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}