# OpenAI Plugin Files Path Format: Directory Structure Guide

> Learn the correct OpenAI plugin files path format and directory structure. Place your plugin files in a dedicated subdirectory and ensure your manifest is at .codex-plugin/plugin.json for proper discovery.

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

---

**Place all plugin files inside a dedicated subdirectory of `plugins/` with the required manifest at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) to ensure Codex discovers and resolves paths correctly.**

The OpenAI Plugins repository enforces a strict directory hierarchy for all plugin bundles. Understanding the correct plugin files path format allows Codex to automatically scan, register, and load your extensions by locating the mandatory manifest and optional resources such as skills, commands, and agents.

## Required Directory Structure

According to the repository's [`README.md`](https://github.com/openai/plugins/blob/main/README.md), each plugin must exist as a self-contained bundle under the top-level `plugins/` directory. The system expects the following layout, where `<plugin-name>` represents your plugin's unique identifier:

```

plugins/
└─ <plugin-name>/
   ├─ .codex-plugin/
   │   └─ plugin.json          ← required manifest
   ├─ skills/                  ← optional skill definitions
   ├─ commands/                ← optional deterministic commands
   ├─ agents/                  ← optional reviewer agents
   ├─ assets/                  ← optional branding assets
   └─ … (other optional files)

```

### The Mandatory Manifest Location

The **manifest must be located at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)** inside the plugin folder. Codex discovers plugins by scanning for this specific file path. Without this exact structure, Codex cannot recognize the directory as a valid plugin bundle, regardless of other contents present. As implemented in `openai/plugins`, this is the sole discovery mechanism used by the scanner.

### Path Resolution Rules

When referencing a plugin, you use the path `<repo-root>/plugins/<plugin-name>` as the base directory. All internal resources—including `skills/`, `commands/`, `assets/`, and optional files like [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) or [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)—resolve relative to this root. The repository README explicitly states that companion surfaces reside as siblings to the `.codex-plugin/` directory, not within it.

## Marketplace Registration

While the directory structure enables local discovery, registering your plugin in the marketplace indexes ensures global availability. Codex reads [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) and [`.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/api_marketplace.json) to map plugin IDs to their filesystem paths. Each entry in these JSON files points to the relative path `plugins/<plugin-name>/`, connecting the identifier to the physical location.

## Practical Implementation Examples

### Minimal Plugin Scaffold

Create the mandatory directory structure and manifest from the repository root:

```bash
mkdir -p plugins/my-awesome-plugin/.codex-plugin
cat > plugins/my-awesome-plugin/.codex-plugin/plugin.json <<'EOF'
{
  "name": "my-awesome-plugin",
  "description": "A short description of what the plugin does",
  "author": "Your Name",
  "version": "0.1.0"
}
EOF

```

### Adding Optional Skills

Place skill definitions in the `skills/` subdirectory at the plugin root:

```bash
mkdir -p plugins/my-awesome-plugin/skills/example
cat > plugins/my-awesome-plugin/skills/example/SKILL.md <<'EOF'
description: Example skill that echoes user input
...
EOF

```

### Updating the Marketplace Index

Register the plugin in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) to enable discovery:

```json
{
  "plugins": [
    {
      "id": "my-awesome-plugin",
      "path": "plugins/my-awesome-plugin"
    }
  ]
}

```

## Summary

- **Place plugin files under `plugins/<plugin-name>/`** to establish the proper root path for resolution
- **The manifest must exist at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)**—this exact path is required for Codex recognition
- **Optional resources** (skills, commands, agents, assets) live as sibling directories to `.codex-plugin/`
- **Marketplace files** [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) and [`api_marketplace.json`](https://github.com/openai/plugins/blob/main/api_marketplace.json) map plugin IDs to their physical locations
- **Internal paths resolve relative** to the plugin's root directory, not the repository root

## Frequently Asked Questions

### What happens if I place the plugin.json file in the wrong location?

Codex will fail to discover the plugin. The discovery mechanism specifically scans for [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) within immediate subdirectories of `plugins/`. Placing the manifest at the root of `plugins/my-plugin/` or in a differently named folder like `config/` will prevent registration and the plugin will not load.

### Can I organize plugins using nested directories like `plugins/category/my-plugin/`?

No. The scanner expects an immediate child directory of `plugins/` containing the `.codex-plugin/` folder. Deeply nested structures are not supported by the default discovery system and will be ignored during the scanning process.

### How does Codex resolve paths to optional resources like skills and commands?

Codex resolves all paths relative to the plugin root (`plugins/<plugin-name>/`). When you define a skill in [`skills/example/SKILL.md`](https://github.com/openai/plugins/blob/main/skills/example/SKILL.md), Codex constructs the full path by appending [`skills/example/SKILL.md`](https://github.com/openai/plugins/blob/main/skills/example/SKILL.md) to the plugin's base directory. This relative resolution applies to all companion surfaces including `commands/`, `agents/`, and `assets/`.

### Is registering in marketplace.json required for local development?

No. For local testing, Codex can detect plugins directly from the `plugins/` directory structure if local scanning is enabled. However, adding your plugin to [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) is required for the plugin to appear in the global marketplace index and for distribution to other users through the OpenAI ecosystem.