# How to Add Custom Skills to OpenAI Codex: A Complete Developer Guide > Learn to add custom skills to OpenAI Codex with this developer guide. Follow simple steps to integrate new capabilities and enhance your code generation. - Repository: [OpenAI/skills](https://github.com/openai/skills) - Tags: how-to-guide - Published: 2026-02-16 --- **You add custom skills to OpenAI Codex by creating self-contained folders with a [`README.md`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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: ```bash # 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`](https://github.com/openai/skills/blob/main/README.md) to document your skill's capabilities: ```bash 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: ```bash # 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: ```bash $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: ```bash 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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/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`](https://github.com/openai/skills/blob/main/LICENSE.txt) file specifying the licensing terms. While the agent primarily looks for the [`README.md`](https://github.com/openai/skills/blob/main/README.md) to understand the skill's capabilities, complete skills include all necessary code and documentation to function independently.