OpenAI Plugin Files Path Format: Directory Structure Guide

Place all plugin files inside a dedicated subdirectory of plugins/ with the required manifest at .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, 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 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 or .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 and .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:

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:

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 to enable discovery:

{
  "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—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 and 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 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, Codex constructs the full path by appending 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 is required for the plugin to appear in the global marketplace index and for distribution to other users through the OpenAI ecosystem.

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