What Are the Different Types of Skills Available in OpenAI? A Complete Guide

OpenAI’s skills repository organizes reusable capabilities into three distinct categories: System skills, Curated skills, and Experimental skills.

The openai/skills repository provides a framework for packaging prompts, scripts, and configurations into modular units called skills. Understanding the different types of skills available in OpenAI is essential for developers who want to extend Codex or build custom agent capabilities. Each skill type serves a specific purpose, from core system functionality to production-ready automations and early-stage prototypes.

The Three Types of Skills Available in OpenAI

OpenAI categorizes skills based on stability, support level, and installation requirements. The repository structure in skills/ reflects this taxonomy through specific subdirectories.

System Skills

System skills reside in skills/.system/ and provide foundational functionality required for Codex to operate. These skills are pre-installed automatically and cannot be removed by end users.

The most critical system skill is the skill-installer itself, located at skills/.system/skill-installer/. This skill enables the discovery and installation of other skill types. Key implementation files include:

• SKILL.md – Defines the skill’s metadata and human-readable description
• scripts/list-skills.py – Scans curated directories and outputs available skills
• scripts/install-skill-from-github.py – Handles download and installation logic using git sparse checkout

System skills follow the same directory structure as other types but are protected from user modification to ensure platform stability.

Curated Skills

Curated skills represent production-ready, recommended capabilities stored in skills/.curated/. These skills undergo review and maintenance by OpenAI, making them the preferred choice for most use cases.

Users install curated skills on demand using the $skill-installer command. Notable examples include:

• yeet – Automates Git workflows (stage, commit, push) with intelligent message generation
• openai-docs – Generates documentation based on OpenAI’s style guidelines

Each curated skill contains:

• SKILL.md with front-matter metadata (name, description, metadata)
• agents/openai.yaml defining the agent prompt template and configuration
• scripts/ directory with executable helpers (Python, Bash, etc.)
• Optional references/ and assets/ for documentation and visual resources

Experimental Skills

Experimental skills occupy skills/.experimental/ when present, though this directory may not exist in all repository tags. These skills represent early-stage prototypes, beta features, or community contributions that have not yet achieved curated status.

Installation requires explicit path specification:

$skill-installer --path skills/.experimental/my-skill

Experimental skills follow identical structural conventions to curated skills but may contain unstable APIs, incomplete documentation, or breaking changes between commits. The README.md at the repository root documents the availability and risks of experimental skills.

How OpenAI Skills Are Structured

Regardless of type, every skill adheres to a standardized directory layout that enables automatic discovery and execution. This consistency allows the $skill-installer to handle System, Curated, and Experimental skills uniformly.

Core Components

• SKILL.md – The entry point containing YAML front-matter with name, description, and optional metadata. The installer parses this file to display human-readable information in the skill list.
• agents/openai.yaml – Configures the AI agent’s behavior, including system prompts, temperature settings, and tool specifications. Codex loads this configuration when invoking the skill.
• scripts/ – Contains executable files that implement the skill’s functionality. These may be Python scripts (like list-skills.py), Bash scripts (like deploy.sh), or other automation tools.
• references/ – Supporting documentation, API specifications, or code snippets that provide context for the skill’s operation.
• assets/ – Images, SVGs, or other media files used in documentation or UI rendering within Codex.

Installation Process

When you execute $skill-installer <skill-name>, the system performs the following operations as implemented in install-skill-from-github.py:

1. Validates the skill exists in skills/.curated/ or the specified path
2. Performs a git sparse checkout to download only the skill’s directory
3. Copies the skill folder to $CODEX_HOME/skills/<skill-name>
4. Validates the presence of required files (SKILL.md, agents/openai.yaml)

System skills bypass this process since they are bundled with the Codex installation.

Working with Skills: Practical Examples

The following examples demonstrate how to interact with the different types of skills available in OpenAI using the command-line tools and Python SDK.

Listing Available Skills

To view all curated skills that can be installed:

$skill-installer list

This command executes list-skills.py, which scans skills/.curated/ and extracts metadata from each SKILL.md file. The output displays skill names and descriptions in a numbered list.

Installing a Curated Skill

To install the yeet skill for Git automation:

$skill-installer yeet

For experimental skills, specify the full path:

$skill-installer --path skills/.experimental/my-prototype

Behind the scenes, this invokes install-skill-from-github.py, which handles authentication via GITHUB_TOKEN if accessing private repositories, performs sparse checkout, and installs dependencies if specified in the skill configuration.

Invoking Skills Programmatically

Once installed, skills integrate with the Codex Python SDK:

from codex import Agent

agent = Agent(model="gpt-4o-mini")
response = agent.run(
    """
    Use the **yeet** skill to stage, commit, and push a change.
    Description: "fix typo in README"
    """
)
print(response)

The agent loads the skill’s agents/openai.yaml configuration from $CODEX_HOME/skills/yeet/ to determine the system prompt and available tools.

Summary

OpenAI’s skills repository organizes capabilities into three distinct categories:

• System skills (skills/.system/) provide core platform functionality like the skill-installer itself and come pre-installed with Codex
• Curated skills (skills/.curated/) represent production-ready, recommended tools such as yeet and openai-docs that users install on demand
• Experimental skills (skills/.experimental/) offer early-stage prototypes and beta features requiring explicit path specification during installation

All skill types follow a standardized structure centered on SKILL.md metadata and agents/openai.yaml configuration, enabling consistent discovery via list-skills.py and installation via install-skill-from-github.py.

Frequently Asked Questions

What is the difference between system skills and curated skills in OpenAI?

System skills are pre-installed core components stored in skills/.system/ that provide essential platform functionality like the skill-installer itself. Curated skills reside in skills/.curated/ and are optional, production-ready tools that users must explicitly install using $skill-installer <name>.

How do I install an experimental skill from the OpenAI skills repository?

Experimental skills require explicit path specification since they reside in skills/.experimental/. Use the command $skill-installer --path skills/.experimental/<skill-name> to install them. Note that this directory may not exist in all repository tags, and these skills may contain unstable APIs.

What files are required to create a custom skill for OpenAI?

Every skill requires a SKILL.md file containing YAML front-matter with name and description fields, and an agents/openai.yaml file defining the agent configuration and prompts. Optional directories include scripts/ for executables, references/ for documentation, and assets/ for media files.

Can I use the OpenAI skills system with private repositories?

Yes, the skill-installer supports private repositories by respecting the GITHUB_TOKEN environment variable. When set, install-skill-from-github.py uses this token for authentication during the git sparse checkout process, allowing access to private skills repositories.

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