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

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 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: Enumerates available skills from a GitHub path and marks installed ones
• install-skill-from-github.py: Downloads or sparse-checks-out a skill into $CODEX_HOME/skills
• 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

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:

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

No pip install steps are required since list-skills.py and 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:

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 script queries the GitHub API to enumerate skills at a specific path:

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

For programmatic integration, request JSON output:

./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:

./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:

./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:

./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:

export GITHUB_TOKEN=ghp_your_personal_access_token

The 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:

./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:

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

The 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:

# 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, 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 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 or creating one manually in $CODEX_HOME/skills, you must restart the Codex process to discover the new SKILL.md descriptor and make the skill available for invocation.

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