# How to Set Up a Development Environment for OpenAI Skills: A Complete Guide

> Easily set up a development environment for OpenAI skills. Clone the repository, configure CODEX_HOME, and use installer scripts for local skill management. Get started now.

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

---

**Set up a development environment for OpenAI skills by cloning the repository, configuring the `$CODEX_HOME` directory (defaulting to `~/.codex`), and using the built-in installer scripts to manage skills locally.**

Setting up a development environment for OpenAI skills allows you to browse, edit, and test self-contained skill folders that the Codex agent runtime can discover and invoke. This guide walks through configuring your local workspace using the official `openai/skills` repository, managing the `$CODEX_HOME/skills` directory, and utilizing the pure-Python helper scripts that require no external dependencies.

## Understanding the OpenAI Skills Architecture

OpenAI skills are organized as discrete folders within a specific directory structure that Codex monitors at runtime. Understanding this layout is essential before modifying or creating new skills.

### Directory Structure

The canonical layout under `$CODEX_HOME` (which defaults to `~/.codex`) follows this pattern:

```

$CODEX_HOME/
└── skills/
    ├── .system/            # Pre-installed core skills (no installation needed)

    ├── .curated/           # Curated public skills from the repository

    └── <your-local-skill>  # Custom skills you are developing

```

Codex reads any folder under `$CODEX_HOME/skills` that contains a [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) descriptor file. These skills become available immediately after a Codex restart.

### Key Components

The repository includes several critical components for skill management:

- **`skills/.system/skill-installer/scripts/`**: Contains the core management scripts
- **[`list-skills.py`](https://github.com/openai/skills/blob/main/list-skills.py)**: Enumerates available skills from a GitHub path and marks installed ones
- **[`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py)**: Downloads or sparse-checks-out a skill into `$CODEX_HOME/skills`
- **[`github_utils.py`](https://github.com/openai/skills/blob/main/github_utils.py)**: Handles authenticated GitHub API requests using `GITHUB_TOKEN` or `GH_TOKEN` environment variables

All scripts use only the Python standard library, eliminating dependency management overhead.

## Prerequisites and Initial Setup

Begin by cloning the repository and preparing your environment to run the management scripts.

### Clone the Repository

```bash
git clone https://github.com/openai/skills.git
cd skills

```

This gives you access to the curated skills under `skills/.curated/` and the system installer scripts.

### Configure Python Environment (Optional)

While the scripts require only the standard library, creating a virtual environment is recommended for isolation:

```bash
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

```

No `pip install` steps are required since [`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) have zero external dependencies.

### Set the Codex Home Directory

By default, the installer uses `~/.codex` as `$CODEX_HOME`. To override this:

```bash
export CODEX_HOME="${HOME}/my-codex"

```

The installer creates `$CODEX_HOME/skills` automatically when you install your first skill.

## Installing and Managing Skills

With the environment configured, use the helper scripts to inspect and install skills from the repository.

### Listing Available Skills

The [`list-skills.py`](https://github.com/openai/skills/blob/main/list-skills.py) script queries the GitHub API to enumerate skills at a specific path:

```bash
chmod +x skills/.system/skill-installer/scripts/*.py
./skills/.system/skill-installer/scripts/list-skills.py

```

For programmatic integration, request JSON output:

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

```

The script marks already-installed skills by checking the contents of `$CODEX_HOME/skills`.

### Installing Curated Skills

To install a specific skill from the curated collection:

```bash
./skills/.system/skill-installer/scripts/install-skill-from-github.py \
    --repo openai/skills \
    --path skills/.curated/gh-address-comments

```

You can install multiple skills in one command by repeating the `--path` argument:

```bash
./skills/.system/skill-installer/scripts/install-skill-from-github.py \
    --repo openai/skills \
    --path skills/.curated/gh-address-comments \
    --path skills/.curated/gh-fix-ci

```

Alternatively, use a raw GitHub URL:

```bash
./skills/.system/skill-installer/scripts/install-skill-from-github.py \
    --url https://github.com/openai/skills/tree/main/skills/.curated/gh-address-comments

```

### Installing from Private Repositories

To access private repositories or avoid rate limits, export a GitHub token:

```bash
export GITHUB_TOKEN=ghp_your_personal_access_token

```

The [`github_utils.py`](https://github.com/openai/skills/blob/main/github_utils.py) module automatically detects `GITHUB_TOKEN` or `GH_TOKEN` and includes it in API request headers. For repositories requiring authentication that the default zip download cannot satisfy, force git mode:

```bash
./skills/.system/skill-installer/scripts/install-skill-from-github.py \
    --repo private-org/private-skills \
    --path skills/secret-skill \
    --method git

```

## Developing Custom Skills

To create new skills rather than installing existing ones, set up a local development folder under `$CODEX_HOME/skills`.

Create your skill directory and add the required descriptor:

```bash
mkdir -p $CODEX_HOME/skills/my-custom-skill
touch $CODEX_HOME/skills/my-custom-skill/SKILL.md

```

The [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) file must contain the skill manifest that Codex uses to understand the skill's purpose and entry points. Refer to the templates in `skills/.system/skill-creator/` for the canonical structure.

After creating or modifying a skill, restart Codex to reload the skill registry:

```bash

# Command depends on your Codex installation

codex restart

```

## Summary

- **Clone the repository** from `https://github.com/openai/skills` to access curated skills and installer scripts.
- **Configure `$CODEX_HOME`** (defaults to `~/.codex`) to define where skills are installed and developed.
- **Use the standard-library-only scripts** ([`list-skills.py`](https://github.com/openai/skills/blob/main/list-skills.py), [`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py)) to manage skills without external dependencies.
- **Authenticate with `GITHUB_TOKEN`** when accessing private repositories or avoiding API rate limits.
- **Restart Codex** after installing or modifying skills to refresh the skill registry.

## Frequently Asked Questions

### What is the default location for installed OpenAI skills?

By default, the installer scripts place skills in `~/.codex/skills` (the `$CODEX_HOME/skills` directory). You can override this by setting the `CODEX_HOME` environment variable before running any installer commands.

### Do I need to install Python dependencies to run the skill installer scripts?

No. The helper scripts located in `skills/.system/skill-installer/scripts/` use only the Python standard library. You do not need to run `pip install` or manage a [`requirements.txt`](https://github.com/openai/skills/blob/main/requirements.txt) file, though creating a virtual environment is recommended for workspace isolation.

### How do I install a skill from a private GitHub repository?

Export a personal access token as `GITHUB_TOKEN` or `GH_TOKEN` before running the installer. If the repository requires authentication that prevents zip downloads, add the `--method git` flag to force a sparse checkout instead of the default zip extraction.

### Why isn't my newly installed skill showing up in Codex?

Codex reads the skill registry at startup. After installing a skill using [`install-skill-from-github.py`](https://github.com/openai/skills/blob/main/install-skill-from-github.py) or creating one manually in `$CODEX_HOME/skills`, you must restart the Codex process to discover the new [`SKILL.md`](https://github.com/openai/skills/blob/main/SKILL.md) descriptor and make the skill available for invocation.