# OpenAI Plugin Development Documentation: Complete Guide to Building Codex Plugins

> Find the official OpenAI plugin development documentation in the openai/plugins repository. Explore guides and examples to build your own Codex plugins.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: documentation
- Published: 2026-07-06

---

**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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/README.md) provides the entry point for all developers. This file explains the required [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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](https://github.com/openai/plugins/blob/main/README.md#L5-L7)).

### Plugin Manifest Specification

The definitive reference for the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) schema lives at [`.agents/skills/plugin-creator/references/plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/.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](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md#L1-L30)).

### Reference Implementation

For a concrete example of a production-ready plugin, examine [`plugins/plugin-eval/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json). After either configuration, restart Codex to rescan the marketplace ([lines 54-71](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/README.md#L54-L71)).

### Configuring the Marketplace File

Add entries to [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) following this structure:

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

```javascript
// 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`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/.codex-plugin/plugin.json) ([lines 1-12](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/.codex-plugin/plugin.json#L1-L12)).

### Invoking Plugin Skills via CLI

Run plugin functionality directly from the command line:

```bash

# 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](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/README.md#L60-L68)).

## 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`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md), defining every valid field for [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json).
- **Every plugin requires a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md), which documents all required fields and acceptable values for OpenAI plugin development.