Directory Structure for Codex Plugin Skills: Complete Guide

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 for documentation.

The .codex-plugin/ Manifest Folder

The .codex-plugin/ directory stores the 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, 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 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, 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 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 — 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 and nested scripts/ directory
• 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 — 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:

# 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), a skills/ directory, and a README.md
• Skill level: Individual skills reside in -skill suffixed folders containing 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 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. 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 specification and the scripts/ directory containing implementation code.

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