# What Is the Structure of an OpenAI Skill? A Complete Guide to the Codex Skill Format

> Explore the structure of an OpenAI skill. Learn how skills use a standardized folder format with SKILL.md, agent definitions, scripts, and assets for the Codex runtime.

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

---

**An OpenAI skill is a self-contained folder that follows a strict convention, containing a [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) file with YAML front-matter metadata, an optional [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml) UI definition, and standardized subdirectories for scripts, assets, and documentation that the Codex runtime discovers automatically.**

The `openai/skills` repository defines this canonical layout so that the Codex agent runtime can discover, install, and execute reusable capabilities without additional configuration. Understanding the structure of an OpenAI skill is essential for developers building custom tools that integrate seamlessly with OpenAI Agents.

## Core Components of an OpenAI Skill Structure

Every skill resides in its own directory under `skills/.curated/<skill-name>/` and follows a predictable schema. The runtime relies on specific files and folders to extract metadata, render UI elements, and invoke executable logic.

### SKILL.md: Metadata and Documentation

The [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) file serves as the single source of truth for a skill's identity and user-facing documentation. It must begin with a YAML front-matter block that the [`list-skills.py`](https://github.com/openai/skills/blob/main/list-skills.py) installer parses to generate skill catalogs.

According to the source code in [`skills/.system/skill-installer/scripts/list-skills.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/scripts/list-skills.py), the installer extracts the `name` and `description` fields from this front-matter to populate the skill registry.

The remainder of [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) contains standard markdown documentation, including prerequisites, workflow steps, and usage examples. For example, [`skills/.curated/yeet/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.curated/yeet/SKILL.md) demonstrates this pattern with a YAML header followed by detailed execution instructions.

### agents/openai.yaml: UI Interface Definition

The optional [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml) file defines how the OpenAI chat UI presents the skill to users. This configuration specifies display names, icons, and default prompts that appear in the agent interface.

Located at `skills/.curated/<skill-name>/agents/openai.yaml`, this file typically contains an `interface` block with properties such as `display_name`, `short_description`, `icon_small`, `icon_large`, and `default_prompt`. The [`skills/.curated/yeet/agents/openai.yaml`](https://github.com/openai/skills/blob/main/skills/.curated/yeet/agents/openai.yaml) and [`skills/.curated/playwright/agents/openai.yaml`](https://github.com/openai/skills/blob/main/skills/.curated/playwright/agents/openai.yaml) files provide concrete implementations of this schema.

### assets/: Icons and Visual Assets

The `assets/` subdirectory stores images and icons referenced by [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml). These visual elements render in the skill catalog and chat interface to provide visual context for users.

Typical contents include PNG icons and SVG graphics, such as `skills/.curated/yeet/assets/yeet.png` or `skills/.curated/playwright/assets/playwright.png`. The paths in [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml) typically reference these files with relative paths like `./assets/icon.png`.

### scripts/: Executable Helpers

The `scripts/` directory contains executable files—bash scripts, Python utilities, or compiled binaries—that implement the skill's core functionality. The workflow described in [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) invokes these scripts to perform tasks.

For example, [`skills/.curated/playwright/scripts/playwright_cli.sh`](https://github.com/openai/skills/blob/main/skills/.curated/playwright/scripts/playwright_cli.sh) provides a command-line interface wrapper that the Playwright skill uses to execute browser automation commands. These scripts must have appropriate execute permissions and shebang lines for the Codex runtime to invoke them directly.

### references/: Supplemental Documentation

The optional `references/` folder contains additional markdown files that provide detailed technical documentation, CLI references, or advanced workflow tips. These files extend the primary [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) without cluttering the main documentation.

The [`skills/.curated/playwright/references/cli.md`](https://github.com/openai/skills/blob/main/skills/.curated/playwright/references/cli.md) file exemplifies this pattern, offering detailed command-line options that users can consult after installing the skill.

### LICENSE.txt: Skill-Specific Licensing

Each skill must include a [`LICENSE.txt`](https://github.com/openai/skills/blob/main/LICENSE.txt) file at its root to specify the legal terms governing its use and redistribution. This file ensures compliance with open-source licensing requirements while allowing individual skills to specify different terms from the parent repository.

Examples include [`skills/.curated/yeet/LICENSE.txt`](https://github.com/openai/skills/blob/main/skills/.curated/yeet/LICENSE.txt), which typically contains standard MIT or Apache 2.0 license text.

## Directory Layout and File Organization

The canonical directory structure ensures that the Codex runtime and skill installer can traverse the repository predictably. A typical skill follows this exact hierarchy:

```

skills/
└── .curated/
    └── <skill-name>/                ← Root folder for the skill
        ├── SKILL.md                 ← Metadata and documentation
        ├── LICENSE.txt              ← Legal terms
        ├── agents/
        │   └── openai.yaml          ← UI configuration (optional)
        ├── assets/                  ← Icons and images (optional)
        │   ├── <icon>.png
        │   └── <icon>-small.svg
        ├── scripts/                 ← Executable logic (optional)
        │   └── <script>.sh / .py
        └── references/              ← Extended docs (optional)
            └── *.md

```

The system-level installer located at [`skills/.system/skill-installer/scripts/list-skills.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/scripts/list-skills.py) recursively scans the `.curated/` directory to discover skills. It parses the YAML front-matter from each [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) to build the skill catalog, then copies the entire skill directory to the user's `$CODEX_HOME/skills/` directory while preserving the internal structure.

## Minimal Skill Skeleton Example

To create a functional skill, you only need a few essential files. Below is a complete minimal example that demonstrates the required structure:

```yaml

# SKILL.md

---
name: "my-skill"
description: "Brief one-sentence summary of what the skill does."
---

## Prerequisites

- List any external tools (e.g. `git`, `node`, …)

## Workflow

1. Describe the step-by-step commands.
2. Show example CLI calls (`$ my-skill do-thing`).

```

```yaml

# agents/openai.yaml

interface:
  display_name: "My Skill"
  short_description: "One-liner for UI"
  icon_small: "./assets/my-skill-small.svg"
  icon_large: "./assets/my-skill.png"
  default_prompt: "Run my-skill with appropriate arguments."

```

```bash

# scripts/run.sh

#!/usr/bin/env bash
set -euo pipefail

# Example helper used by the workflow

echo "Running my-skill with args: $@"

```

After placing these files under `skills/.curated/my-skill/`, the skill installer will automatically detect and list the skill, and Codex agents can invoke it via the defined prompt.

## How the Codex Runtime Discovers Skills

The discovery mechanism relies on the consistent directory structure described above. The [`list-skills.py`](https://github.com/openai/skills/blob/main/list-skills.py) script in `skills/.system/skill-installer/scripts/` performs the following operations:

1. **Scanning**: It recursively searches the `.curated/` directory for folders containing [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) files.
2. **Parsing**: It extracts the YAML front-matter from each [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) to obtain the `name` and `description` fields.
3. **Installation**: It copies the entire skill directory to the user's `$CODEX_HOME/skills/` directory, preserving the internal folder hierarchy so that relative paths (e.g., `./assets/icon.png`) remain valid.

Because the structure is uniform, the runtime can locate [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml) for UI rendering, execute scripts from the `scripts/` directory, and display documentation from [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) without additional configuration.

## Summary

- An **OpenAI skill** is a self-contained directory under `skills/.curated/<skill-name>/` that packages reusable functionality for Codex agents.
- **SKILL.md** provides YAML front-matter metadata (name, description) and markdown documentation describing prerequisites and workflow.
- **agents/openai.yaml** optionally defines UI presentation elements including display names, icons, and default prompts.
- **assets/**, **scripts/**, and **references/** folders contain supporting resources, executable logic, and extended documentation respectively.
- **LICENSE.txt** specifies the legal terms for each individual skill.
- The **skill-installer** ([`list-skills.py`](https://github.com/openai/skills/blob/main/list-skills.py)) automatically discovers skills by parsing [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) front-matter and copying the directory structure to the user's Codex home directory.

## Frequently Asked Questions

### What is the minimum required file to create a valid OpenAI skill?

At minimum, a skill requires a [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) file containing YAML front-matter with `name` and `description` fields, followed by markdown documentation. While optional folders like `scripts/` or `agents/` enhance functionality, the runtime only strictly requires the [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) metadata to list and identify the skill.

### How does the Codex runtime locate the executable scripts for a skill?

The runtime executes scripts from the `scripts/` subdirectory within the skill folder, using relative paths specified in the [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) workflow documentation. When the skill installer copies the skill directory to `$CODEX_HOME/skills/`, it preserves the internal hierarchy, ensuring that commands like [`./scripts/run.sh`](https://github.com/openai/skills/blob/main/./scripts/run.sh) resolve correctly during execution.

### Is the agents/openai.yaml file mandatory for all skills?

No, the [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml) file is optional. It is only required if you want the skill to appear in the OpenAI chat UI with custom icons, display names, or default prompts. Skills without this file can still be discovered and executed by the Codex runtime as long as they contain a valid [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md).

### Where should I place license information for my custom skill?

Each skill must include a [`LICENSE.txt`](https://github.com/openai/skills/blob/main/LICENSE.txt) file at the root of the skill directory (e.g., [`skills/.curated/my-skill/LICENSE.txt`](https://github.com/openai/skills/blob/main/skills/.curated/my-skill/LICENSE.txt)). This file should contain the full text of the license governing the skill's use, allowing individual skills to specify different terms from the parent repository while ensuring compliance with open-source distribution requirements.