OpenAI Plugin Development Documentation: Complete Guide to Building Codex Plugins

The official OpenAI plugin development documentation lives entirely within the openai/plugins repository as Markdown files and JSON manifests, with the core specification located in .agents/skills/plugin-creator/references/plugin-json-spec.md and practical examples in plugins/plugin-eval/.

The openai/plugins repository serves as a self-contained knowledge base for OpenAI plugin development documentation. Every resource required to build, publish, and deploy Codex plugins lives inside this repository as version-controlled Markdown files and structured JSON manifests. Whether you are creating your first plugin or managing a team-wide plugin marketplace, the repository contains the complete technical specification and reference implementations.

Core Documentation Locations

The repository organizes OpenAI plugin development documentation across several critical paths. Each location serves a distinct purpose in the plugin lifecycle, from initial specification reading to deployment configuration.

Repository Overview and Quick Start

The top-level README.md provides the entry point for all developers. This file explains the required .codex-plugin/plugin.json manifest location and outlines the standard plugin layout. According to the source code, every plugin must reside under plugins/<plugin-name>/ with a valid manifest at its root (see README line 5-7).

Plugin Manifest Specification

The definitive reference for the plugin.json schema lives at .agents/skills/plugin-creator/references/plugin-json-spec.md. This file specifies every field, type, and required value for the manifest that defines your plugin's identity, version, author, and UI metadata. The specification covers both the plugin structure and the marketplace JSON format (lines 1-30).

Reference Implementation

For a concrete example of a production-ready plugin, examine plugins/plugin-eval/.codex-plugin/plugin.json. This manifest demonstrates the actual implementation used by the plugin-eval tool, showing how theoretical specifications translate to working code. The accompanying documentation at plugins/plugin-eval/README.md provides end-to-end guidance including installation procedures and CLI usage.

Marketplace Configuration

Codex discovers plugins through .agents/plugins/marketplace.json. This file can exist in the user home directory (~/.agents/plugins/marketplace.json) for personal plugin collections or in the repository root for team-wide distribution. The marketplace entries point to plugin paths using relative references, enabling Codex to load plugins without hard-coded absolute locations.

Plugin Architecture Deep Dive

Understanding the architectural components is essential for effective OpenAI plugin development.

The Plugin Root and Manifest

Every plugin requires a root directory under plugins/<plugin-name>/ containing a .codex-plugin/plugin.json file. This manifest serves as the single source of truth for the plugin's metadata. The file must define the plugin name, version, author information, and entry points that Codex uses to initialize the plugin.

Skills Directory Structure

Optional skills/ directories within plugin folders contain Markdown-based skill definitions (SKILL.md). Codex invokes these skills during execution. The manifest references these skills via the "skills" field, typically using a relative path like ./skills/. Each skill file provides human-readable instructions that guide Codex's behavior.

Marketplace Discovery Mechanism

The discovery system relies on marketplace.json entries that specify plugin locations and policies. The configuration supports two scopes:

• Personal scope: ~/.agents/plugins/marketplace.json for individual developer tools
• Repository scope: .agents/plugins/marketplace.json for team-wide shared plugins

Each entry includes installation policies and authentication requirements, allowing fine-grained control over plugin availability.

Installation and Configuration Workflows

Deploying plugins requires proper symlink configuration and marketplace updates.

Personal vs. Repository-Wide Installation

Developers can install plugins for personal use by symlinking the plugin folder to ~/plugins/ and updating the personal marketplace file. For team-wide deployment, place the plugin in the repository's ./plugins/ directory and modify .agents/plugins/marketplace.json. After either configuration, restart Codex to rescan the marketplace (lines 54-71).

Configuring the Marketplace File

Add entries to marketplace.json following this structure:

{
  "name": "local",
  "interface": { "displayName": "Local Plugins" },
  "plugins": [
    {
      "name": "my-awesome-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-awesome-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

Place this configuration in ~/.agents/plugins/marketplace.json for personal use or .agents/plugins/marketplace.json for repository-wide access. Ensure the plugin folder exists at the specified relative path before restarting Codex.

Practical Code Examples

Loading a Plugin Manifest in Node.js

Access plugin metadata programmatically by reading the plugin.json file:

// Load the manifest for any plugin in the repo
import { readFile } from "fs/promises";
import path from "path";

async function loadManifest(pluginName) {
  const manifestPath = path.join(
    __dirname,
    "plugins",
    pluginName,
    ".codex-plugin",
    "plugin.json"
  );
  const raw = await readFile(manifestPath, "utf8");
  const manifest = JSON.parse(raw);
  console.log(`Plugin ${manifest.name} v${manifest.version}`);
  console.log(`Description: ${manifest.description}`);
  return manifest;
}

// Example usage
loadManifest("plugin-eval");

This implementation mirrors the manifest structure defined in plugins/plugin-eval/.codex-plugin/plugin.json (lines 1-12).

Invoking Plugin Skills via CLI

Run plugin functionality directly from the command line:

# From the repository root

node ./plugins/plugin-eval/scripts/plugin-eval.js start ./plugins/plugin-eval \
  --request "Give me an analysis of this plugin." \
  --format markdown

This command syntax follows the CLI usage documentation (lines 60-68).

Summary

• The openai/plugins repository contains the complete OpenAI plugin development documentation as Markdown files and JSON specifications, requiring no external documentation sources.
• The canonical manifest specification resides at .agents/skills/plugin-creator/references/plugin-json-spec.md, defining every valid field for plugin.json.
• Every plugin requires a .codex-plugin/plugin.json manifest at its root, serving as the single source of truth for metadata and configuration.
• Marketplace discovery operates through marketplace.json files that support both personal (~/.agents/plugins/) and repository-wide (.agents/plugins/) scopes.
• Installation requires symlinking the plugin directory and updating the appropriate marketplace configuration before restarting Codex.

Frequently Asked Questions

Where is the official OpenAI plugin manifest specification located?

The official specification lives at .agents/skills/plugin-creator/references/plugin-json-spec.md within the openai/plugins repository. This document defines all required and optional fields for the plugin.json manifest, including data types, validation rules, and marketplace integration formats.

How do I install a plugin for personal use versus team-wide use?

For personal use, symlink your plugin to ~/plugins/ and update ~/.agents/plugins/marketplace.json. For team-wide deployment, place the plugin in the repository's ./plugins/ directory and modify the .agents/plugins/marketplace.json file at the repository root. Both methods require restarting Codex to load the new configuration.

What is the purpose of the marketplace.json file?

The marketplace.json file tells Codex where to find plugins and how to handle them. It specifies plugin paths, installation policies (such as AVAILABLE or REQUIRED), and authentication requirements. This file enables the dynamic discovery system that allows Codex to load plugins from both local directories and remote sources without hard-coded paths.

How do I validate a plugin manifest programmatically?

Load the plugin.json file using standard filesystem methods and parse it as JSON. The manifest must contain valid name, version, and description fields at minimum. For strict validation, compare your manifest structure against the specification in .agents/skills/plugin-creator/references/plugin-json-spec.md, which documents all required fields and acceptable values for OpenAI plugin development.

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