# OpenAI Plugin Directory Structure: Required Layout for Codex Development

> Discover the required directory structure for OpenAI Codex plugin development. Learn about the essential manifest and skill entry points for seamless integration.

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

---

**Yes, OpenAI Codex requires a strict directory structure that mandates a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/figma/.app.json).

### MCP Server Declaration (.mcp.json)

The [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json)**: The default plugin catalogue used by standard OpenAI platform logins
- **[`.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest
- Skills require a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) entry point located at `skills/<skill-name>/SKILL.md`
- Optional files include [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) register the plugin for the platform catalogue, making it available to users.