# How to Install Curated and Experimental Skills Using the Skill-Installer in OpenAI Skills

> Learn how to install curated and experimental skills from the openai/skills repository using simple skill-installer scripts. Effortlessly add new capabilities to your projects.

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

---

**You can install curated and experimental skills from the openai/skills repository using the skill-installer scripts [`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), which download skills into your `$CODEX_HOME/skills` directory.**

The **skill-installer** is a helper bundle within the `openai/skills` repository that automates discovering and adding Codex skills to your local environment. It distinguishes between **curated skills** (stable, reviewed capabilities in `skills/.curated`) and **experimental skills** (cutting-edge features in `skills/.experimental`), providing the same installation workflow for both categories.

## Understanding the Skill-Installer Architecture

The installer operates through three core Python scripts located in `skills/.system/skill-installer/scripts/`, coordinated by documentation in [`skills/.system/skill-installer/SKILL.md`](https://github.com/openai/skills/blob/main/skills/.system/skill-installer/SKILL.md).

### Core Components

- **[`list-skills.py`](https://github.com/openai/skills/blob/main/list-skills.py)**: Queries the GitHub Contents API to enumerate directories under `skills/.curated` or `skills/.experimental`. It cross-references your local `$CODEX_HOME/skills` directory to mark already-installed skills.

- **[`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py)**: Handles the full installation pipeline. It resolves sources via `_resolve_source()`, validates paths with `_validate_relative_path()`, prepares repositories through `_prepare_repo()` (using either `_download_repo_zip()` or `_git_sparse_checkout()`), validates skill structure via `_validate_skill()`, and copies files using `_copy_skill()`.

- **[`github_utils.py`](https://github.com/openai/skills/blob/main/github_utils.py)**: Provides shared HTTP helpers for authenticated GitHub requests, automatically detecting `GITHUB_TOKEN` or `GH_TOKEN` environment variables.

### Installation Workflow

When you run the installer, it executes a deterministic sequence: parse arguments, resolve the GitHub URL (supporting `--url` via `_parse_github_url()` or `--repo`/`--path` combinations), fetch the repository content, verify the presence of [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) to confirm valid skill structure, and copy the skill into `$CODEX_HOME/skills/<skill-name>` (defaulting to `~/.codex/skills` if `$CODEX_HOME` is unset).

## Listing Available Skills

Before installing, you can browse available skills using the listing script, which supports both curated and experimental repositories.

### List Curated Skills

By default, [`list-skills.py`](https://github.com/openai/skills/blob/main/list-skills.py) targets the curated collection:

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

```

The script outputs a numbered text list:

```

1. yeet
2. speech
3. notion-spec-to-implementation
...
Which ones would you like installed?

```

### List Experimental Skills

To browse cutting-edge capabilities, specify the experimental path:

```bash
python skills/.system/skill-installer/scripts/list-skills.py \
  --path skills/.experimental

```

### JSON Output Format

For programmatic access or CI/CD pipelines, request machine-readable output:

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

```

This returns a structured array: `[{ "name": "yeet", "installed": true }, ...]`.

## Installing Skills

The [`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py) script provides flexible options for adding skills to your local environment.

### Install a Single Curated Skill

To install a specific curated skill:

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

```

The script executes `_download_repo_zip()` or `_git_sparse_checkout()` to fetch content, validates the skill structure via `_validate_skill()` (checking for [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md)), and copies the result to `~/.codex/skills/yeet` (or `$CODEX_HOME/skills/yeet`).

### Install Multiple Skills

You can batch-install by providing multiple `--path` arguments:

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

```

Each path installs under its own directory name (basename of the path).

### Install Experimental Skills

The process is identical for experimental capabilities—only the path changes:

```bash
python skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo openai/skills \
  --path skills/.experimental/<skill-name>

```

Replace `<skill-name>` with the specific experimental skill directory identified via [`list-skills.py`](https://github.com/openai/skills/blob/main/list-skills.py).

### Install from Custom URLs or Forks

To install from a fork, specific branch, or full GitHub URL:

```bash
python skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --url https://github.com/yourname/skills/tree/feature-branch/skills/.curated/yeet

```

The script uses `_parse_github_url()` to extract owner, repo, ref, and sub-path components.

### Custom Destination and Naming

Override default locations and directory names:

```bash
python skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo openai/skills \
  --path skills/.curated/yeet \
  --dest /my/custom/skills \
  --name my-yeet

```

- `--dest` overrides `$CODEX_HOME/skills`.
- `--name` renames the installed directory from `yeet` to `my-yeet`.

## Post-Installation Steps

After successfully installing skills, you must restart Codex (or the host process) to load the newly added capabilities. The installer validates skill structure by checking for [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) files, but the runtime discovery occurs only after process restart.

## Summary

- The **skill-installer** in `openai/skills` automates adding curated and experimental skills to your local `$CODEX_HOME/skills` directory.
- Use **[`list-skills.py`](https://github.com/openai/skills/blob/main/list-skills.py)** to browse available skills via the GitHub API, with support for `--path` targeting (`skills/.curated` or `skills/.experimental`) and `--format json` output.
- Use **[`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py)** to download, validate (via [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) checks), and copy skills; it supports multiple paths, custom URLs, forks, and destination overrides.
- Both scripts respect the `$CODEX_HOME` environment variable (defaulting to `~/.codex`) and authenticate via `GITHUB_TOKEN` or `GH_TOKEN` when available.
- Always restart Codex after installation to activate new skills.

## Frequently Asked Questions

### What is the difference between curated and experimental skills in the openai/skills repository?

**Curated skills** are stable, reviewed capabilities stored in `skills/.curated` that have been vetted for reliability and general use. **Experimental skills** live in `skills/.experimental` and represent cutting-edge or beta functionality that may change frequently or have limited testing. Both types install using the same `skill-installer` scripts, but experimental skills may require more frequent updates or troubleshooting.

### How does the skill-installer handle authentication with GitHub?

The installer uses [`github_utils.py`](https://github.com/openai/skills/blob/main/github_utils.py) to manage HTTP requests, automatically detecting `GITHUB_TOKEN` or `GH_TOKEN` environment variables. When present, these tokens are added to request headers to avoid rate limits and access private repositories. If no token is set, the scripts still function for public repositories but may hit GitHub's unauthenticated rate limits during heavy usage.

### Can I install skills to a custom directory outside of ~/.codex?

Yes. While the installer defaults to `$CODEX_HOME/skills` (or `~/.codex/skills` if unset), you can override this using the `--dest` flag with [`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py). For example, `--dest /my/custom/skills` installs the skill to that specific path. You can also rename the installed skill directory using `--name` to avoid conflicts or match your naming conventions.

### What validation does the installer perform before completing an installation?

The installer validates skills by checking for the presence of a [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) file via the `_validate_skill()` function in [`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py). This file must exist at the root of the skill directory to confirm it follows the expected structure. Additionally, the script validates relative paths using `_validate_relative_path()` to prevent directory traversal attacks, and verifies repository accessibility before attempting downloads or sparse checkouts.