# OpenAI Codex Skill Package Structure: A Complete Technical Guide

> Discover the structure of an OpenAI Codex skill package. Learn about mandatory and optional subdirectories like SKILL.md, assets, agents, scripts, and references in this technical guide.

- Repository: [OpenAI/skills](https://github.com/openai/skills)
- Tags: deep-dive
- Published: 2026-02-16

---

**An OpenAI Codex skill package is a self-contained directory with a mandatory [`SKILL.md`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/SKILL.md) and [`scripts/list-skills.py`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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:

```bash
$skill-installer list

```

This executes [`skills/.system/skill-installer/scripts/list-skills.py`](https://github.com/openai/skills/blob/main/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:

```bash
$skill-installer yeet

```

The installer copies `skills/.curated/yeet/` to `~/.codex/skills/yeet/`, including its [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md), `assets/`, and `scripts/`.

### Using the Speech Skill CLI

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

```bash
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`](https://github.com/openai/skills/blob/main/skills/.curated/speech/references/cli.md).

### Creating a GitHub PR with Yeet

Following the workflow defined in [`skills/.curated/yeet/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.curated/yeet/SKILL.md):

```bash

# 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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/SKILL.md) file documents which scripts to use for specific workflows, and the `references/` directory can provide detailed CLI documentation for complex script interfaces.