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

An OpenAI skill is a self-contained folder that follows a strict convention, containing a SKILL.md file with YAML front-matter metadata, an optional 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 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 installer parses to generate skill catalogs.

According to the source code in 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 contains standard markdown documentation, including prerequisites, workflow steps, and usage examples. For example, 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 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 and 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. 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 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 invokes these scripts to perform tasks.

For example, 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 without cluttering the main documentation.

The 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 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, 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 recursively scans the .curated/ directory to discover skills. It parses the YAML front-matter from each 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:

# 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`).

# 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."

# 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 script in skills/.system/skill-installer/scripts/ performs the following operations:

1. Scanning: It recursively searches the .curated/ directory for folders containing SKILL.md files.
2. Parsing: It extracts the YAML front-matter from each 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 for UI rendering, execute scripts from the scripts/ directory, and display documentation from 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) automatically discovers skills by parsing 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 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 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 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 resolve correctly during execution.

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

No, the 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.

Where should I place license information for my custom skill?

Each skill must include a LICENSE.txt file at the root of the skill directory (e.g., 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.

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