# Directory Structure for Codex Plugin Skills: Complete Guide

> Understand the directory structure for Codex plugin skills. Learn to organize plugins, manifest files, and skill subdirectories for seamless integration.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-10

---

**The directory structure for Codex plugin skills requires a top-level `plugins/` folder containing individual plugin directories, each with a `.codex-plugin/` manifest folder and a `skills/` subdirectory that houses skill-specific folders ending in `-skill`.**

The `openai/plugins` repository implements this standardized hierarchy to organize plugin metadata, skill specifications, and executable scripts. Understanding this directory structure for Codex plugin skills enables developers to correctly package capabilities, ensure proper discovery by the Codex runtime, and maintain consistency across the ecosystem.

## Top-Level Plugin Organization

Every Codex plugin resides as a subdirectory within the root `plugins/` folder. Each plugin directory contains three essential components: a **`.codex-plugin/`** folder for manifests, a **`skills/`** directory for capabilities, and a **[`README.md`](https://github.com/openai/plugins/blob/main/README.md)** for documentation.

### The `.codex-plugin/` Manifest Folder

The `.codex-plugin/` directory stores the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file that defines the plugin's identity, version, and entry points. According to the source code, this manifest is mandatory for plugin recognition.

For example, in [`plugins/render/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/render/.codex-plugin/plugin.json), the manifest declares the render plugin's configuration. This JSON file tells Codex how to load the plugin and what dependencies or permissions it requires.

### The `skills/` Directory

The `skills/` folder contains one or more skill subdirectories, typically named with the suffix `-skill` (e.g., `ukb-topmed-phewas-skill`). This convention distinguishes skill folders from other plugin resources and ensures predictable discovery by the Codex engine.

## Anatomy of a Skill Folder

Each skill folder is a self-contained unit comprising documentation, implementation code, and optional static resources. The structure enforces separation of concerns between human-readable specifications and executable logic.

### SKILL.md Specification

Every skill must include a **[`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md)** file at its root. This markdown document serves as the human-readable specification, describing the skill's purpose, input parameters, output formats, and usage examples.

In [`plugins/life-science-research/skills/ukb-topmed-phewas-skill/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/life-science-research/skills/ukb-topmed-phewas-skill/SKILL.md), the specification defines how the UK Biobank PheWAS skill processes genetic data. This file acts as the contract between the skill developer and users, documenting expected behavior without requiring code inspection.

### The `scripts/` Directory

The **`scripts/`** folder contains the executable implementation files that provide the skill's runtime logic. These are typically Python files, though other languages may be supported depending on the Codex runtime configuration.

For instance, [`plugins/life-science-research/skills/ukb-topmed-phewas-skill/scripts/ukb_topmed_phewas.py`](https://github.com/openai/plugins/blob/main/plugins/life-science-research/skills/ukb-topmed-phewas-skill/scripts/ukb_topmed_phewas.py) contains the actualPython implementation that executes when the skill is invoked. The script name usually mirrors the skill name for clarity.

### Optional `assets/` Folder

Skills may include an **`assets/`** directory for static resources such as icons, images, or configuration templates. While optional, this folder is recommended for skills that provide user interface elements or require external data files.

## Real-World Repository Examples

The `openai/plugins` repository demonstrates this directory structure through concrete implementations:

- **[`plugins/render/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/render/.codex-plugin/plugin.json)** — Shows the mandatory manifest location for the render plugin
- **`plugins/life-science-research/skills/ukb-topmed-phewas-skill/`** — Illustrates a complete skill folder with [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) and nested `scripts/` directory
- **[`plugins/life-science-research/skills/ukb-topmed-phewas-skill/scripts/ukb_topmed_phewas.py`](https://github.com/openai/plugins/blob/main/plugins/life-science-research/skills/ukb-topmed-phewas-skill/scripts/ukb_topmed_phewas.py)** — Provides a reference implementation showing where executable code resides
- **[`plugins/codex-security/scripts/render_report_html.py`](https://github.com/openai/plugins/blob/main/plugins/codex-security/scripts/render_report_html.py)** — Demonstrates that while some plugins may place scripts at the plugin root, the standard pattern places them within skill-specific `scripts/` folders

## Navigating and Working with Skills

Use these command-line operations to explore and execute skills following the standard directory structure:

```bash

# List all installed plugins in the local Codex home directory

ls ~/.codex/plugins

# Display skill directories for a specific plugin

ls ~/.codex/plugins/life-science-research/skills

# Open a skill's markdown specification for review

open ~/.codex/plugins/life-science-research/skills/ukb-topmed-phewas-skill/SKILL.md

# Execute a skill's script directly for debugging or standalone use

python ~/.codex/plugins/life-science-research/skills/ukb-topmed-phewas-skill/scripts/ukb_topmed_phewas.py \
    --gene-id 12345

```

## Summary

The directory structure for Codex plugin skills enforces a clear organizational pattern:

- **Root level**: The `plugins/` directory contains all plugin installations
- **Plugin level**: Each plugin has a `.codex-plugin/` folder (containing [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)), a `skills/` directory, and a [`README.md`](https://github.com/openai/plugins/blob/main/README.md)
- **Skill level**: Individual skills reside in `-skill` suffixed folders containing [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md), a `scripts/` folder with implementation code, and optionally an `assets/` folder
- **Implementation level**: Executable scripts live in `scripts/` and define the skill's runtime behavior

## Frequently Asked Questions

### What is the purpose of the `.codex-plugin` folder?

The `.codex-plugin` folder stores the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest file that Codex uses to identify, load, and configure the plugin. This hidden directory separates machine-readable metadata from user-facing documentation and skill implementations, ensuring the runtime can quickly parse plugin capabilities without scanning unrelated files.

### Can skills exist outside the `skills/` directory?

While the standard convention places all skills within the `skills/` subdirectory, some plugins like `codex-security` demonstrate alternative layouts where scripts reside directly under the plugin root. However, the recommended and most common pattern follows the `skills/<name>-skill/` hierarchy for consistency and maintainability.

### What file types belong in the `scripts/` folder?

The `scripts/` folder typically contains **Python files** (`.py`) that implement the skill's logic, as seen in [`ukb_topmed_phewas.py`](https://github.com/openai/plugins/blob/main/ukb_topmed_phewas.py). These executable scripts handle input processing, API calls, data transformation, and output generation. The specific language depends on the Codex runtime, but Python is the primary language used in the `openai/plugins` repository.

### Is the `assets/` folder required for every skill?

No, the `assets/` folder is **optional**. Skills that do not require icons, images, or static configuration files can omit this directory entirely. The mandatory components are the [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) specification and the `scripts/` directory containing implementation code.