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

You can install curated and experimental skills from the openai/skills repository using the skill-installer scripts list-skills.py and 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.

Core Components

• 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: 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: 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 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 targets the curated collection:

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:

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:

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 script provides flexible options for adding skills to your local environment.

Install a Single Curated Skill

To install a specific curated skill:

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), 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:

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:

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.

Install from Custom URLs or Forks

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

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:

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 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 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 to download, validate (via 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 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. 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 file via the _validate_skill() function in 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.

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