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

An OpenAI Skill is a self-contained package that declares its purpose in SKILL.md, configures its UI in 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 file serves as the canonical description of what the skill does. Located at paths like 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 file (e.g., 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 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.

references/ and assets/: Supporting Resources

• references/: Documentation, sample prompts, and CLI usage guides (e.g., 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 queries the GitHub API using github_api_contents_url defined in 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

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

Installation Process

The install-skill-from-github.py script downloads the skill folder into $CODEX_HOME/skills/<skill-name>. The $skill-installer command wraps this functionality:

skill-installer speech

This internally executes:

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 to understand intent, prerequisites, and workflow
2. Present UI: Render the interface defined in 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)
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

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

skill-installer speech

This command runs 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

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

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.

Summary

• OpenAI Skills follow a convention-driven structure separating metadata (SKILL.md), UI configuration (agents/openai.yaml), and implementation (scripts/).
• Discovery happens via list-skills.py using the GitHub API through 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 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, 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 file serves as the canonical definition, located at the root of each skill folder (e.g., 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 (e.g., 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 script, which is wrapped by the $skill-installer command. The 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 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.

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