OpenAI Plugin Directory Structure: Required Layout for Codex Development

Yes, OpenAI Codex requires a strict directory structure that mandates a .codex-plugin/plugin.json manifest at plugins/<plugin-name>/.codex-plugin/plugin.json and skill entry points at skills/<skill-name>/SKILL.md.

The openai/plugins repository defines a standardized mono-repo layout that enables automatic discovery and loading of plugins. Every plugin must reside under the top-level plugins/ directory and follow specific conventions for manifests, skills, and optional assets. Understanding the exact OpenAI plugin directory structure ensures your integration is compatible with the runtime and marketplace.

Required Root Structure

Every plugin must live under plugins/<plugin-name>/, where <plugin-name> is the unique identifier for your integration. This folder serves as the root for all plugin-specific files and subdirectories.

According to the source code in openai/plugins, the runtime specifically looks for the manifest at:

plugins/<plugin-name>/
├─ .codex-plugin/
│   └─ plugin.json          <!-- REQUIRED: Plugin manifest -->
└─ skills/                   <!-- REQUIRED: Container for skills -->

The repository root also contains global marketplace configuration files under .agents/plugins/ that register available plugins for the OpenAI platform.

Mandatory Plugin Files

Two files are absolutely required for any functional plugin: the manifest and at least one skill entry point.

The Manifest File (plugin.json)

The .codex-plugin/plugin.json file defines the plugin’s metadata, interface, and skill location. This JSON file must contain valid schema including name, version, description, and a skills property pointing to your skills directory (typically "./skills/").

Key fields in plugin.json:

• name: Unique plugin identifier
• skills: Relative path to skills directory (e.g., "./skills/")
• interface: Object containing displayName, category, brandColor, and icon paths

Example structure from the magicpath plugin:

{
  "name": "magicpath",
  "version": "1.0.0",
  "description": "Repository management tools",
  "skills": "./skills/",
  "interface": {
    "displayName": "MagicPath",
    "category": "Developer Tools",
    "brandColor": "#00AABB"
  }
}

Skill Entry Points (SKILL.md)

Each skill is an atomic unit of functionality contained in its own folder under skills/<skill-name>/. The only required file inside a skill directory is SKILL.md, which serves as the entry point describing capabilities, default prompts, and references.

The file path follows this strict pattern:

plugins/<plugin-name>/skills/<skill-name>/SKILL.md

A SKILL.md file typically includes:

• A short description of the skill's purpose
• Default prompts that trigger the skill
• References to documentation files

Optional Directories and Configuration

Beyond the required manifest and skills, the OpenAI plugin directory structure supports several optional files placed next to the manifest.

Application Configuration (.app.json)

The .app.json file declares a hosted web application associated with the plugin. This is used when the plugin provides a UI companion to the Codex functionality. Example location: plugins/figma/.app.json.

MCP Server Declaration (.mcp.json)

The .mcp.json file configures Model-Capability-Provider (MCP) servers that extend the plugin's capabilities with specific model behaviors or external API integrations.

Agents Directory

The optional agents/ folder contains OpenAI agent configurations (typically openai.yaml files) that implement custom behaviors. These can exist at the plugin level (plugins/<name>/agents/) or within individual skill folders (skills/<skill>/agents/).

UI Assets

The assets/ directory stores icons, screenshots, and other media referenced by the plugin.json interface properties such as composerIcon and logo. Paths in the manifest are relative to the plugin root, for example: "./assets/icon.png".

Skill Organization and Constraints

The skills/ directory has specific organizational rules documented in the repository's CONTRIBUTING.md.

Reference Documentation

Skills may include a references/ subdirectory containing supplementary markdown files (.md) that provide API snippets, troubleshooting guides, or workflow documentation. These are linked from SKILL.md but must be addressed explicitly—the runtime cannot read directories directly, and attempting to do so raises an EISDIR error.

Example skill structure:

skills/<skill-name>/
├─ SKILL.md                 <!-- Required entry point -->
├─ references/
│   ├─ api-examples.md
│   └─ troubleshooting.md
└─ agents/
    └─ openai.yaml          <!-- Optional agent config -->

Depth Limitations

Skill folders must be at most three levels deep. This means skills/<skill>/references/file.md is valid, but deeper nesting violates the repository constraints and may cause discovery failures.

Global Marketplace Files

The repository root contains marketplace configuration that makes plugins discoverable to the OpenAI platform.

• .agents/plugins/marketplace.json: The default plugin catalogue used by standard OpenAI platform logins
• .agents/plugins/api_marketplace.json: Alternative catalogue for users authenticated with API keys

These JSON files point to the plugins/ directory and define which integrations appear in the marketplace.

Summary

• Every plugin must reside under plugins/<plugin-name>/ with a mandatory .codex-plugin/plugin.json manifest
• Skills require a SKILL.md entry point located at skills/<skill-name>/SKILL.md
• Optional files include .app.json, .mcp.json, agents/, and assets/ directories
• Reference files must be individual markdown documents; directories cannot be read directly
• Skill folders are limited to a maximum nesting depth of three levels
• Global marketplace configuration lives in .agents/plugins/marketplace.json

Frequently Asked Questions

What is the minimum required file structure for an OpenAI Codex plugin?

The absolute minimum requires two files: plugins/<name>/.codex-plugin/plugin.json (the manifest) and plugins/<name>/skills/<skill-name>/SKILL.md (at least one skill entry point). While assets/ and references/ directories are recommended for complete functionality, the runtime only strictly requires the manifest and skill entry point to load a plugin.

Can I nest skill directories deeper than three levels?

No, the OpenAI Codex runtime enforces a maximum depth of three levels for skill directories as documented in CONTRIBUTING.md. Attempting to use deeper nesting may result in discovery failures or EISDIR errors when the system attempts to read directory structures.

Where should I place UI assets like icons and screenshots?

Place all UI assets in an assets/ directory at the plugin root level (plugins/<plugin-name>/assets/), then reference them in plugin.json using relative paths such as "./assets/icon.png". The manifest's interface object supports composerIcon, logo, and other asset references that display in the OpenAI interface.

How does the OpenAI runtime discover my plugin?

The runtime discovers plugins by scanning the plugins/ directory for folders containing .codex-plugin/plugin.json manifests. The skills property in the manifest tells the system where to locate skill entry points. Global marketplace files in .agents/plugins/marketplace.json register the plugin for the platform catalogue, making it available to users.

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