How to Navigate the OpenAI Skills Repository: A Complete Guide to Skill Discovery and Installation

The OpenAI Skills repository organizes agent capabilities into self-contained directories under skills/.curated/ and skills/.system/, which you can explore via the GitHub UI, local clone, or the $skill-installer CLI that ships with Codex.

The openai/skills repository on GitHub serves as the central registry for agent capabilities used by OpenAI Codex. Whether you are looking to install a pre-built skill or understand how the system organizes its components, knowing how to navigate the OpenAI skills repository efficiently will save you time and prevent configuration errors.

Repository Structure Overview

The repository follows a strict hierarchical layout that separates system-level utilities from user-contributed capabilities.

Top-Level Organization

At the root, you will find:

• README.md – High-level introduction and installation basics.
• contributing.md – Guidelines for adding new skills or improving existing ones.
• skills/ – The main directory containing all skill packages organized into subcategories.

The Three Skill Tiers

Inside skills/, the repository divides capabilities into three distinct categories:

1. skills/.system/ – Core system skills pre-installed in every Codex instance. This includes the skill-installer itself, which enables listing and installing other skills.
2. skills/.curated/ – Production-ready skills contributed by the community that have been vetted by OpenAI. Each subdirectory here is a standalone skill (e.g., yeet, security-threat-model, imagegen).
3. skills/.experimental/ (optional) – Early-stage skills that are not automatically installed. This directory follows the same structure as .curated but may contain unstable features.

Anatomy of a Skill Package

To effectively navigate the OpenAI skills repository, you must understand the internal structure of an individual skill directory.

Required Files

Every valid skill must contain:

• SKILL.md – The skill manifest located at the root of the skill folder. This file defines the skill's name, description, prerequisites, workflow, and usage notes. For example, skills/.curated/yeet/SKILL.md describes the workflow for GitHub PR creation.
• agents/openai.yaml – An OpenAI-compatible YAML file that describes how the agent invokes the skill. This configuration file maps natural language commands to the skill's execution logic.

Optional Assets and Scripts

Depending on complexity, a skill may also include:

• assets/ – Images, SVGs, or other media used for documentation or UI rendering (e.g., skills/.curated/yeet/assets/yeet.png).
• scripts/ – Helper scripts required at runtime for the skill to function.
• references/ – Additional markdown documentation that the skill manifest links to for extended reading.

Navigating via the Command Line

While browsing the GitHub UI provides visual orientation, the most efficient way to navigate and manage skills is through the skill-installer CLI provided in the Codex environment.

Listing Available Skills

The list-skills.py script in skills/.system/skill-installer/scripts/ queries the repository to show available capabilities. To list all curated skills from your terminal:

$skill-installer list-skills

This command scans the default path (skills/.curated) and outputs a numbered list indicating which skills are already installed locally:

Skills from openai/skills:
1. yeet
2. security-threat-model (already installed)
3. imagegen
...

To explore experimental skills instead, specify the path explicitly:

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

Installing Curated Skills

The install-skill-from-github.py script handles the download and installation process. To install a curated skill such as yeet:

$skill-installer install yeet

Behind the scenes, this executes:

python -m skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo openai/skills \
  --path skills/.curated/yeet

The script performs the following actions:

1. Downloads the repository ZIP (or performs a sparse git checkout as fallback).
2. Validates the presence of SKILL.md to ensure package integrity.
3. Copies the skill into $CODEX_HOME/skills/yeet.

Important: After installing any skill, you must restart Codex to load the new capability. The installer prints the message: "Restart Codex to pick up new skills."

Installing from External Repositories

You are not limited to the official openai/skills repository. The install-skill-from-github.py script accepts any public GitHub URL via the --url parameter. For example:

$skill-installer install \
  --url https://github.com/username/custom-skills/tree/main/skills/.curated/my-skill

The installer parses the URL, downloads the repository ZIP, extracts the specified skill directory, validates it against the skill schema, and installs it under $CODEX_HOME/skills/my-skill.

Programmatic Usage

For automation or integration with other tools, you can invoke the installer programmatically using Python's subprocess module:

import subprocess
import json

# List skills with JSON output for easier parsing

result = subprocess.run(
    ["$skill-installer", "list-skills", "--format", "json"],
    capture_output=True,
    text=True,
    check=True,
)

skills = json.loads(result.stdout)
print("Available skills:", [s["name"] for s in skills])

# Install a specific skill

subprocess.run(
    ["$skill-installer", "install", "imagegen"],
    check=True,
)
print("Installed imagegen – restart Codex to use it.")

Key Files and Their Locations

Understanding the location of critical files helps you navigate the OpenAI skills repository efficiently:

File	Role	Location
README.md	High-level introduction and installation basics	[README.md](https://github.com/openai/skills/blob/main/README.md)
contributing.md	Guidelines for adding new skills	[contributing.md](https://github.com/openai/skills/blob/main/contributing.md)
skill-installer/SKILL.md	Manifest for the system-level installer skill	[skills/.system/skill-installer/SKILL.md](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/SKILL.md)
list-skills.py	CLI helper that queries the GitHub API for skill listings	[skills/.system/skill-installer/scripts/list-skills.py](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/scripts/list-skills.py)
install-skill-from-github.py	Core installer that downloads, validates, and copies a skill	[skills/.system/skill-installer/scripts/install-skill-from-github.py](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/scripts/install-skill-from-github.py)
yeet/SKILL.md	Example of a fully-fledged skill manifest	[skills/.curated/yeet/SKILL.md](https://github.com/openai/skills/blob/main/skills/.curated/yeet/SKILL.md)
imagegen/SKILL.md	Another curated skill showing a different use-case	[skills/.curated/imagegen/SKILL.md](https://github.com/openai/skills/blob/main/skills/.curated/imagegen/SKILL.md)

Summary

• The OpenAI Skills repository organizes agent capabilities into three tiers: .system (pre-installed), .curated (production-ready), and .experimental (early-stage).
• Each skill is a self-contained directory requiring SKILL.md and agents/openai.yaml, with optional scripts/, assets/, and references/ folders.
• The skill-installer system skill provides list-skills.py and install-skill-from-github.py for CLI-based navigation and installation.
• You can explore the repository through the GitHub web interface, a local git clone, or programmatically via Python subprocess calls to the installer commands.
• After installing any skill, you must restart Codex to load the new capability into the agent environment.

Frequently Asked Questions

How do I know which skills are already installed on my system?

Run $skill-installer list-skills from your terminal. The output appends "(already installed)" next to any skill present in your local $CODEX_HOME/skills directory. The script skills/.system/skill-installer/scripts/list-skills.py queries the GitHub API for the remote skill list and cross-references it against your local filesystem to generate this status.

Can I install skills from repositories other than openai/skills?

Yes. The install-skill-from-github.py script accepts any public GitHub URL via the --url parameter. For example, you can run $skill-installer install --url https://github.com/username/custom-skills/tree/main/skills/.curated/my-skill to fetch from a fork or entirely separate project. The installer validates the downloaded package by checking for a valid SKILL.md manifest before copying it to $CODEX_HOME/skills/.

What is the difference between .system and .curated skills?

.system skills reside in skills/.system/ and ship pre-installed with every Codex instance. They provide core infrastructure, such as the skill-installer itself located at skills/.system/skill-installer/. .curated skills live in skills/.curated/ and represent community-contributed, production-ready capabilities (like yeet or imagegen) that you must explicitly install. Unlike system skills, curated skills can be added or removed without affecting Codex core functionality.

Why must I restart Codex after installing a new skill?

Codex loads skill manifests into memory at startup to build the command registry available to the agent. When install-skill-from-github.py copies a new skill into $CODEX_HOME/skills/, the runtime environment does not dynamically watch for filesystem changes. Restarting Codex forces a fresh load of the SKILL.md manifests and agents/openai.yaml configurations, making the newly installed commands available for use.

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