How to Add Custom Skills to OpenAI Codex: A Complete Developer Guide

You add custom skills to OpenAI Codex by creating self-contained folders with a README.md and executable scripts in the skills/.experimental/ directory, installing them via the $skill-installer command, and restarting Codex to load the new capabilities.

The openai/skills repository provides the infrastructure for extending Codex with custom capabilities. When you add custom skills to OpenAI Codex, you create Agent Skills—self-contained packages that bundle instructions, scripts, and resources that Codex agents can discover and execute automatically.

Understanding the OpenAI Skills Repository Structure

The repository organizes capabilities into three distinct categories based on stability and distribution method.

Skill Categories (.system, .curated, .experimental)

Each skill resides in a specific subdirectory under skills/ that determines its installation behavior:

• skills/.system/ — Contains skills automatically installed in every Codex release. These are core capabilities required for basic functionality.

• skills/.curated/ — Houses stable, reviewed skills that users install by name. These have passed quality review and are distributed through the official installer.

• skills/.experimental/ — Stores work-in-progress skills installable directly from a folder path or GitHub URL. This is the recommended location for developing new custom skills before submitting for curation.

Standard Skill Directory Layout

Every skill folder must contain specific files to be recognized by the Codex agent system:

• README.md — Describes the skill's purpose, usage instructions, and any configuration requirements.
• Executable scripts — The actual code the agent runs (Python, shell, or other supported languages).
• LICENSE.txt — License information for the skill's code and resources.

Step-by-Step Guide to Adding Custom Skills to OpenAI Codex

Follow this workflow to create, install, and activate a new skill in your Codex environment.

Step 1: Create Your Skill Folder

Navigate to the repository's skills/ directory and create a new folder under .experimental/ for development:

# Clone the repository if you haven't already

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

# Create your custom skill directory

mkdir -p skills/.experimental/my-custom-skill

Step 2: Define Skill Metadata and Scripts

Create the required README.md to document your skill's capabilities:

cat > skills/.experimental/my-custom-skill/README.md <<'EOF'

# My Custom Skill

This skill demonstrates custom functionality for OpenAI Codex.
It provides utilities for [specific task description].

## Usage

The agent will automatically invoke this skill when [trigger condition].
EOF

Add any executable scripts your skill requires to the same directory.

Step 3: Install Using the Skill Installer

Codex provides the $skill-installer command-line tool to register new capabilities. For experimental skills, specify the local path or GitHub URL:

# Install from local directory

$skill-installer install ./skills/.experimental/my-custom-skill

# Or install directly from GitHub URL

$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan

For curated skills already in the repository, install by name only:

$skill-installer gh-address-comments

Step 4: Restart Codex to Load the Skill

After installation, you must restart the Codex environment to discover and load the new skill:

codex restart

Once restarted, the Codex agent will recognize your custom skill and make it available for task execution.

Publishing Your Skill to the Official Repository

If you want your skill distributed to other users, submit it to the openai/skills repository:

1. Ensure your skill follows the standard directory layout with complete documentation.
2. Move or copy your skill from .experimental/ to .curated/ if it meets stability requirements, or keep it in .experimental/ for community testing.
3. Open a pull request against the main branch with a description of the skill's functionality and use cases.
4. Wait for review and approval from the maintainers.

Summary

To add custom skills to OpenAI Codex, remember these key points:

• Create self-contained skill folders under skills/.experimental/ with a README.md and required scripts.
• Use the $skill-installer command to register local paths, GitHub URLs, or curated skill names.
• Always restart Codex after installation to load new capabilities.
• Submit pull requests to the openai/skills repository to distribute skills to other users.

Frequently Asked Questions

What is the difference between .system, .curated, and .experimental skills?

System skills in skills/.system/ are automatically installed with every Codex release and provide core functionality. Curated skills in skills/.curated/ are stable, reviewed capabilities that users install by name using the skill installer. Experimental skills in skills/.experimental/ are work-in-progress features that can be installed directly from a local folder or GitHub URL for testing and development.

Can I install a custom skill directly from a GitHub repository without cloning it locally?

Yes, the $skill-installer supports direct installation from GitHub URLs. Use the command $skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/[skill-name] to install an experimental skill directly from the repository without needing to clone the entire repository to your local machine first.

Why do I need to restart Codex after installing a new skill?

Codex loads available skills during its initialization sequence. When you install a new skill using the $skill-installer, the skill files are placed in the appropriate directory, but the running Codex process has already completed its discovery phase. Restarting Codex triggers a fresh skill discovery process that scans the skills/ directories and loads the newly installed capability into the agent's available toolset.

What files are required for a skill to be recognized by the Codex agent?

At minimum, a skill must contain a README.md file that describes the skill's purpose and usage instructions. The directory should also include any executable scripts that implement the skill's functionality, and a LICENSE.txt file specifying the licensing terms. While the agent primarily looks for the README.md to understand the skill's capabilities, complete skills include all necessary code and documentation to function independently.

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