Where to Find OpenAI Plugins Documentation: The Complete Guide to the Official Repository

All OpenAI plugins documentation lives inside the openai/plugins repository as Markdown files and JSON manifests that define the Codex plugin ecosystem.

The openai/plugins repository serves as the self-contained knowledge base for building, publishing, and using Codex plugins. Whether you are creating a new plugin or installing an existing one, every specification, example, and operational guide resides within this repository as version-controlled documentation.

Core Documentation Locations

The repository organizes documentation by function, from high-level overviews to granular technical specifications.

Repository Overview and Getting Started

Start with README.md at the repository root ([README.md](https://github.com/openai/plugins/blob/main/README.md)). This file provides the general overview of the plugin layout and explains the required .codex-plugin/plugin.json manifest location (see lines 5‑7). It also lists highlighted plugins and explains the basic directory structure.

Plugin Manifest Specification

For the complete technical specification of the plugin manifest, reference .agents/skills/plugin-creator/references/plugin-json-spec.md (Plugin JSON spec). This document defines every field in plugin.json, including types, required values, and the marketplace JSON format (lines 1‑30). It serves as the single source of truth for manifest design.

Working Examples and Reference Implementations

Study plugins/plugin-eval/.codex-plugin/plugin.json (plugin‑eval manifest) for a real-world example of a complete manifest. For end-to-end documentation covering installation, CLI usage, and skill reference, see plugins/plugin-eval/README.md (plugin‑eval README), which demonstrates how individual plugins document their capabilities.

Marketplace Configuration

Codex discovers plugins through marketplace.json, which can reside at .agents/plugins/marketplace.json for team-wide collections or in the user's home directory (~/.agents/plugins/marketplace.json) for personal collections (Marketplace example). This file tells Codex where plugins live and how to load them without hard-coding absolute paths.

Repository Architecture for Plugin Development

Understanding the file structure is essential for navigating the OpenAI plugins documentation effectively.

Plugin Root Structure

Every plugin must live under plugins/<plugin-name>/. The .codex-plugin/plugin.json file within each plugin directory is the single source of truth for the plugin's identity, version, author, and UI metadata. The root-level README.md explicitly states that this manifest is required for any valid plugin.

Skills Directory

Optional skills/ directories within plugin folders hold Markdown-based skill definitions (SKILL.md) that Codex can invoke. Each skill is referenced from the manifest via the "skills" field (e.g., "./skills/"). These files document the specific capabilities the plugin exposes to the Codex runtime.

Installation and Discovery Flow

The documentation outlines two installation scopes found in plugins/plugin-eval/README.md (lines 54‑71):

1. Personal installation: Symlink the plugin folder into ~/plugins and update ~/.agents/plugins/marketplace.json
2. Workspace installation: Place the plugin in ./plugins and update .agents/plugins/marketplace.json

After updating the marketplace configuration, restart Codex to trigger a rescan.

Practical Examples for Accessing Documentation

These runnable examples demonstrate how to programmatically interact with the documentation structure.

Loading a Plugin Manifest in Node.js

This script reads the canonical plugin.json file for any plugin in the repository:

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");

Source: The manifest structure follows the example at plugins/plugin-eval/.codex-plugin/plugin.json (lines 1‑12).

Configuring a Personal Marketplace Entry

To add a plugin to your local Codex environment, create or update ~/.agents/plugins/marketplace.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"
    }
  ]
}

Implementation steps:

1. Place the JSON snippet in ~/.agents/plugins/marketplace.json
2. Ensure the plugin folder exists at ~/plugins/my-awesome-plugin
3. Restart Codex to load the plugin

This format mirrors the marketplace specification detailed in .agents/skills/plugin-creator/references/plugin-json-spec.md (lines 1‑30).

Invoking Plugin CLI Tools

Many plugins, such as plugin-eval, ship with command-line interfaces documented in their respective README files:

# 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

Source: CLI usage is documented in plugins/plugin-eval/README.md (lines 60‑68), ensuring the command reference stays synchronized with the implementation.

Summary

• Primary entry point: The root README.md provides the high-level overview and manifest requirements for the openai/plugins repository.
• Technical specification: .agents/skills/plugin-creator/references/plugin-json-spec.md contains the definitive reference for all plugin.json fields and marketplace configurations.
• Working examples: plugins/plugin-eval/.codex-plugin/plugin.json and its corresponding README demonstrate real-world implementation patterns.
• Discovery mechanism: .agents/plugins/marketplace.json controls how Codex locates and loads plugins for both personal and team-wide use.
• Programmatic access: Node.js scripts can load manifests directly from plugins/<name>/.codex-plugin/plugin.json to validate or inspect plugin metadata.

Frequently Asked Questions

What is the minimum file required to create a valid OpenAI plugin?

You must include a plugin.json manifest file located at .codex-plugin/plugin.json within your plugin directory. According to the repository root README.md (lines 5‑7), this file is the single source of truth for the plugin's identity and is required for Codex to recognize the plugin.

How does Codex discover plugins in the repository?

Codex uses the marketplace.json file for discovery. This file can exist at .agents/plugins/marketplace.json for repository-wide plugins or at ~/.agents/plugins/marketplace.json for personal collections. Each entry points to the plugin's relative path, enabling Codex to load plugins dynamically without absolute file paths.

Where can I find the official specification for plugin.json manifest fields?

The complete specification resides at .agents/skills/plugin-creator/references/plugin-json-spec.md. This document defines every valid field, data type, and required value for the plugin manifest, including the marketplace JSON structure that controls installation policies and authentication requirements.

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 (repository) use, place the plugin in the repository's ./plugins directory and update the .agents/plugins/marketplace.json file at the repository root. The plugins/plugin-eval/README.md (lines 54‑71) provides detailed step-by-step instructions for both methods, including how to restart Codex to complete the installation.

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