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

> Locate official OpenAI plugins documentation within the openai/plugins repository. This guide details Markdown files and JSON manifests for the Codex plugin ecosystem.

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

---

**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`](https://github.com/openai/plugins/blob/main/README.md)** at the repository root ([[`README.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md)** ([Plugin JSON spec](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md)). This document defines every field in [`plugin.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/.codex-plugin/plugin.json)** ([plugin‑eval manifest](https://github.com/github.com/openai/plugins/blob/main/plugins/plugin-eval/.codex-plugin/plugin.json)) 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`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/README.md)** ([plugin‑eval README](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/README.md)), which demonstrates how individual plugins document their capabilities.

### Marketplace Configuration

Codex discovers plugins through **[`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json)**, which can reside at **[`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json)** for team-wide collections or in the user's home directory (`~/.agents/plugins/marketplace.json`) for personal collections ([Marketplace example](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json)). 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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugin.json) file for any plugin in the repository:

```javascript
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`](https://github.com/openai/plugins/blob/main/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`:

```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`](https://github.com/openai/plugins/blob/main/.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:

```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

```

*Source:* CLI usage is documented in [`plugins/plugin-eval/README.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.agents/skills/plugin-creator/references/plugin-json-spec.md) contains the definitive reference for all [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) fields and marketplace configurations.
- **Working examples**: [`plugins/plugin-eval/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/plugin-eval/.codex-plugin/plugin.json) and its corresponding README demonstrate real-world implementation patterns.
- **Discovery mechanism**: [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugin.json)** manifest file located at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) within your plugin directory. According to the repository root [`README.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/marketplace.json)** file for discovery. This file can exist at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) file at the repository root. The [`plugins/plugin-eval/README.md`](https://github.com/openai/plugins/blob/main/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.