# How to Understand the Functionality of an OpenAI Skill: A Complete Technical Guide

> Master OpenAI skills with this technical guide. Learn how skills declare purpose, configure UI, and execute logic for seamless integration.

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

---

**An OpenAI Skill is a self-contained package that declares its purpose in [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md), configures its UI in [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml), and executes logic via scripts in the `scripts/` directory, making it discoverable and runnable by any Codex-enabled agent.**

To understand the functionality of an OpenAI Skill, you need to examine its convention-driven directory structure and runtime contract. Each skill in the `openai/skills` repository follows a standardized anatomy that separates metadata, user interface hints, and implementation logic, enabling automated discovery and execution without custom integration code.

## Anatomy of an OpenAI Skill

Every skill resides in a folder under `skills/` and adheres to a strict file layout that agents parse automatically.

### SKILL.md: The Metadata Layer

The [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) file serves as the canonical description of what the skill does. Located at paths like [`skills/.curated/speech/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.curated/speech/SKILL.md), this markdown file contains:

- **Description**: High-level explanation of the skill's purpose
- **When-to-use**: Conditions that trigger the skill's invocation
- **Prerequisites**: Required environment variables like `OPENAI_API_KEY`
- **Workflow**: Step-by-step execution logic and decision trees

When a Codex agent receives a request, it first loads this metadata to determine if the skill matches the user's intent.

### agents/openai.yaml: UI Configuration

The [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml) file (e.g., [`skills/.curated/speech/agents/openai.yaml`](https://github.com/openai/skills/blob/main/skills/.curated/speech/agents/openai.yaml)) provides display metadata for Codex agents:

- **Display name**: Human-readable title shown in the UI
- **Short description**: Tooltip or subtitle text
- **Icons**: Visual identifiers for the skill
- **Default prompt**: Initial instructions sent to the model when the skill activates

This separation allows the same underlying script to present different interfaces depending on the agent context.

### scripts/: Implementation Logic

The `scripts/` directory contains the actual executable code. For 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 Speech Generation skill by:

1. Parsing CLI arguments (`--text`, `--voice`, `--out`)
2. Validating the `OPENAI_API_KEY` environment variable
3. Calling the OpenAI Audio API using the `openai` Python SDK
4. Respecting rate limits (50 RPM default)
5. Writing output to the specified path

Scripts can be written in Python, shell, or any language, provided they adhere to the input/output contract defined in [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md).

### references/ and assets/: Supporting Resources

- **references/**: Documentation, sample prompts, and CLI usage guides (e.g., [`references/cli.md`](https://github.com/openai/skills/blob/main/references/cli.md))
- **assets/**: Icons, images, and binary files needed for UI rendering
- **LICENSE.txt**: Legal terms governing the skill's usage

## How Skills Are Discovered and Installed

The `skill-installer` system automates the discovery and deployment of skills from the repository.

### Discovery via list-skills.py

The script [`skills/.system/skill-installer/scripts/list-skills.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/scripts/list-skills.py) queries the GitHub API using `github_api_contents_url` defined in [`skills/.system/skill-installer/scripts/github_utils.py`](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/scripts/github_utils.py). It:

- Lists directories under `skills/.curated`
- Checks `$CODEX_HOME/skills` for locally installed copies
- Returns JSON metadata with `installed` flags

```bash
python -m skills/.system/skill-installer/scripts/list-skills.py --format json

```

### Installation Process

The [`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py) script downloads the skill folder into `$CODEX_HOME/skills/<skill-name>`. The `$skill-installer` command wraps this functionality:

```bash
skill-installer speech

```

This internally executes:

```bash
python skills/.system/skill-installer/scripts/install-skill-from-github.py \
    --repo openai/skills \
    --path skills/.curated/speech

```

## Runtime Execution Flow

When a Codex-enabled agent invokes a skill, it follows a strict execution pipeline:

1. **Load Metadata**: Parse [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) to understand intent, prerequisites, and workflow
2. **Present UI**: Render the interface defined in [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml) (icon, description, default prompt)
3. **Collect Inputs**: Gather required parameters (text, voice, format) from the user
4. **Run Implementation**: Execute the script in `scripts/` (e.g., [`text_to_speech.py`](https://github.com/openai/skills/blob/main/text_to_speech.py))
5. **Return Results**: Output files go to `output/<skill-name>/`, temporary data to `tmp/<skill-name>/`

The Speech Generation skill exemplifies this flow: it requires `OPENAI_API_KEY`, defaults to the `gpt-4o-mini-tts-2025-12-15` model, and respects a 50 RPM rate limit.

## Practical Examples: Working with the Speech Skill

### Listing Available Skills

```bash
python -m skills/.system/skill-installer/scripts/list-skills.py --format json

```

This uses `_list_skills()` internally to query the GitHub API and returns JSON with `installed` flags indicating which skills exist locally in `$CODEX_HOME/skills/`.

### Installing the Speech Skill

```bash
skill-installer speech

```

This command runs [`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py) with `--repo openai/skills --path skills/.curated/speech`, downloading the skill to `$CODEX_HOME/skills/speech`.

### Running Text-to-Speech

```bash
cd $CODEX_HOME/skills/speech
python scripts/text_to_speech.py \
    --text "Welcome to the demo." \
    --voice cedar \
    --out output/speech/demo.mp3

```

Behind the scenes, the script builds a JSONL request, calls `openai.Audio.speech()`, and enforces the 50 RPM limit. Output lands in `output/speech/demo.mp3` as specified.

### Using the Default Prompt

```python
prompt = """Generate spoken audio for this text with the right voice style,
pacing, and output format."""

```

The agent sends this prompt together with user text to the skill's workflow defined in [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md).

## Summary

- **OpenAI Skills** follow a convention-driven structure separating metadata ([`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md)), UI configuration ([`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml)), and implementation (`scripts/`).
- **Discovery** happens via [`list-skills.py`](https://github.com/openai/skills/blob/main/list-skills.py) using the GitHub API through [`github_utils.py`](https://github.com/openai/skills/blob/main/github_utils.py), checking against `$CODEX_HOME/skills/` for local copies.
- **Installation** copies skill folders from `skills/.curated/` to the local environment using [`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py) wrapped by the `skill-installer` command.
- **Runtime execution** loads metadata, presents the UI, collects inputs, runs scripts, and manages output directories (`output/` and `tmp/`).
- The **Speech Generation skill** demonstrates this architecture with [`text_to_speech.py`](https://github.com/openai/skills/blob/main/text_to_speech.py), requiring `OPENAI_API_KEY` and defaulting to the `gpt-4o-mini-tts-2025-12-15` model.

## Frequently Asked Questions

### What file defines the core functionality of an OpenAI Skill?

The **[`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md)** file serves as the canonical definition, located at the root of each skill folder (e.g., [`skills/.curated/speech/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.curated/speech/SKILL.md)). This markdown file declares the skill's purpose, prerequisites like `OPENAI_API_KEY`, the decision workflow, and usage instructions that agents parse to determine when and how to invoke the capability.

### How does a Codex agent know how to display a skill in the UI?

The agent reads **[`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml)** (e.g., [`skills/.curated/speech/agents/openai.yaml`](https://github.com/openai/skills/blob/main/skills/.curated/speech/agents/openai.yaml)) to retrieve display metadata including the skill's name, icon, short description, and default prompt. This separation allows the same underlying scripts to present different interfaces depending on the agent context, without modifying the core logic.

### Where are OpenAI Skills installed on my local machine?

Skills are installed into **`$CODEX_HOME/skills/<skill-name>`** by the [`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py) script, which is wrapped by the `$skill-installer` command. The [`list-skills.py`](https://github.com/openai/skills/blob/main/list-skills.py) utility checks this directory to determine which skills are already installed versus available in the remote `skills/.curated/` repository.

### How do I list all available skills from the OpenAI repository?

Run **`python -m skills/.system/skill-installer/scripts/list-skills.py --format json`** to query the GitHub API via [`github_utils.py`](https://github.com/openai/skills/blob/main/github_utils.py) and enumerate directories under `skills/.curated`. This command returns JSON metadata indicating which skills are installed locally in `$CODEX_HOME/skills/` and which are available for installation.