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

> Discover and install agent capabilities from the openai/skills repository. Learn to navigate curated and system skills using the GitHub UI, local clone, or the skill-installer CLI.

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

---

**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`](https://github.com/openai/skills/blob/main/README.md)** – High-level introduction and installation basics.
- **[`contributing.md`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/skills/.curated/yeet/SKILL.md) describes the workflow for GitHub PR creation.
- **[`agents/openai.yaml`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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:

```bash
$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:

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

```

### Installing Curated Skills

The [`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py) script handles the download and installation process. To install a curated skill such as `yeet`:

```bash
$skill-installer install yeet

```

Behind the scenes, this executes:

```bash
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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/install-skill-from-github.py) script accepts any public GitHub URL via the `--url` parameter. For example:

```bash
$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:

```python
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`](https://github.com/openai/skills/blob/main/README.md) | High-level introduction and installation basics | [[`README.md`](https://github.com/openai/skills/blob/main/README.md)](https://github.com/openai/skills/blob/main/README.md) |
| [`contributing.md`](https://github.com/openai/skills/blob/main/contributing.md) | Guidelines for adding new skills | [[`contributing.md`](https://github.com/openai/skills/blob/main/contributing.md)](https://github.com/openai/skills/blob/main/contributing.md) |
| [`skill-installer/SKILL.md`](https://github.com/openai/skills/blob/main/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)](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/SKILL.md) |
| [`list-skills.py`](https://github.com/openai/skills/blob/main/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)](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/scripts/list-skills.py) |
| [`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/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)](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/scripts/install-skill-from-github.py) |
| [`yeet/SKILL.md`](https://github.com/openai/skills/blob/main/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)](https://github.com/openai/skills/blob/main/skills/.curated/yeet/SKILL.md) |
| [`imagegen/SKILL.md`](https://github.com/openai/skills/blob/main/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)](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`](https://github.com/openai/skills/blob/main/SKILL.md) and [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml), with optional `scripts/`, `assets/`, and `references/` folders.
- The **skill-installer** system skill provides [`list-skills.py`](https://github.com/openai/skills/blob/main/list-skills.py) and [`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/SKILL.md) manifests and [`agents/openai.yaml`](https://github.com/openai/skills/blob/main/agents/openai.yaml) configurations, making the newly installed commands available for use.