# OpenAI Plugins Repository Structure: A Complete Guide to the Directory Layout

> Explore the openai plugins repository structure. Understand directory layout, plugin subdirectories, JSON manifests, and marketplace definitions for seamless discovery.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: architecture
- Published: 2026-09-11

---

**The openai/plugins repository follows a modular architecture where each plugin resides in its own subdirectory under `plugins/` with a mandatory JSON manifest, while marketplace definitions in `.agents/plugins/` enable automatic discovery and categorization by the Codex runtime.**

The openai/plugins repository hosts the official reference collection for Codex plugin examples, implementing a standardized filesystem layout that separates configuration, assets, and executable code into predictable locations. This design allows each plugin to function as an independent package while maintaining consistency across categories ranging from Communication to Security.

## Top-Level Directory Layout

The repository root contains three primary components that govern plugin discovery and documentation.

**Repository documentation** resides in [`README.md`](https://github.com/openai/plugins/blob/main/README.md), which introduces the repository’s intent and highlights featured integrations.

**Marketplace definitions** live inside the `.agents/` directory. Specifically, [`/.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main//.agents/plugins/marketplace.json) lists every locally available plugin with its installation policy, authentication mode, and category, while [`/.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main//.agents/plugins/api_marketplace.json) provides an alternative marketplace configuration for API-key-based authentication. Both files auto-generate from the contents of the `plugins/` directory, ensuring the marketplace stays synchronized with the filesystem.

**Plugin packages** occupy the `plugins/` directory, with each subfolder representing a complete, self-contained integration such as `gmail/`, `slack/`, or `github/`.

## Individual Plugin Structure

Every plugin directory under `plugins/<plugin-name>/` follows a mandatory convention for the manifest and supports several optional configuration layers.

### Required Manifest

Each plugin must contain a manifest at `plugins/<plugin-name>/.codex-plugin/plugin.json`. This JSON file defines core metadata including the plugin name, version, description, author, and interface specifications required by the Codex runtime.

### Optional Configuration Files

Beyond the manifest, plugins may include:

- **[`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)** – Links the plugin to a native app connector used by Codex runtimes.
- **[`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)** – Contains Multi-Channel-Protocol definitions for advanced interactions.
- **`assets/`** – Stores UI resources such as icons and screenshots referenced by the manifest.
- **`skills/`** – Houses reusable skill modules exposing functions, agents, or YAML-defined workflows.
- **`agents/`** – Contains YAML files describing Codex agents utilized by the plugin.
- **`tests/`** – Hosts plugin-specific test suites in JavaScript, Python, HTML, or other languages.

For example, the Gmail plugin demonstrates this structure with its manifest at [`plugins/gmail/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/gmail/.codex-plugin/plugin.json), an app connector at [`plugins/gmail/.app.json`](https://github.com/openai/plugins/blob/main/plugins/gmail/.app.json), and UI assets in `plugins/gmail/assets/`.

## Plugin Categories

The repository organizes plugins into functional categories declared in [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json). These include:

- **Communication** – `gmail`, `slack`, `teams`, `outlook-email`, `zoom`
- **Productivity** – `linear`, `notion`, `clickup`, `monday-com`, `airtable`
- **Developer Tools** – `github`, `circleci`, `vercel`, `supabase`, `coderabbit`
- **Creativity** – `figma`, `canva`, `remotion`, `product-design`
- **Finance** – `stripe`, `public-equity-investing`
- **Education & Research** – `zotero`, `life-science-research`, `ngs-analysis`
- **Security** – `codex-security`

Each entry in the marketplace JSON includes a `category` field enabling Codex to filter plugins by domain.

## Developer Tooling and Scaffolding

The repository includes automation utilities under `/.agents/skills/plugin-creator/`. The [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) script assists contributors in scaffolding new plugins that conform to the required layout, while [`plugin-json-spec.md`](https://github.com/openai/plugins/blob/main/plugin-json-spec.md) documents the manifest schema. These tools ensure new submissions automatically appear in the marketplace JSON files upon generation.

## Working with the Repository Programmatically

Consumers can interact with the openai/plugins repository structure using standard filesystem and JSON parsing utilities.

### Loading a Plugin Manifest

The following Python function reads the mandatory [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest for any given plugin name:

```python
import json
from pathlib import Path

def load_manifest(plugin_name: str):
    """Read the .codex-plugin/plugin.json for a given plugin."""
    manifest_path = Path("plugins") / plugin_name / ".codex-plugin" / "plugin.json"
    with manifest_path.open() as f:
        return json.load(f)

gmail_manifest = load_manifest("gmail")
print(gmail_manifest["interface"]["displayName"])   # → Gmail

```

This approach leverages the predictable repository structure to access metadata without hardcoding full paths.

### Enumerating Plugins by Category

To analyze the marketplace configuration programmatically:

```python
import json

def list_plugins_by_category(marketplace_path: str = ".agents/plugins/marketplace.json"):
    with open(marketplace_path) as f:
        data = json.load(f)
    categories = {}
    for entry in data["plugins"]:
        cat = entry["category"]
        categories.setdefault(cat, []).append(entry["name"])
    return categories

categories = list_plugins_by_category()
for cat, plugins in sorted(categories.items()):
    print(f"{cat}: {', '.join(plugins)}")

```

Executing this script outputs a grouped view of the repository contents, such as listing all Communication or Productivity tools available in the marketplace.

## Summary

- The openai/plugins repository uses a modular structure where each plugin occupies an independent subdirectory under `plugins/`.
- Every plugin requires a manifest at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) and may optionally include [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json), assets, skills, agents, and tests.
- Marketplace metadata in [`/.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main//.agents/plugins/marketplace.json) and [`api_marketplace.json`](https://github.com/openai/plugins/blob/main/api_marketplace.json) auto-generates from the `plugins/` directory contents.
- Helper scripts in `/.agents/skills/plugin-creator/` provide scaffolding tools for new plugin development.
- The repository categorizes plugins into domains like Communication, Productivity, and Developer Tools for easy discovery by the Codex runtime.

## Frequently Asked Questions

### Where is the main plugin manifest located in the openai/plugins repository?

Each plugin stores its core metadata in a JSON manifest located at `plugins/<plugin-name>/.codex-plugin/plugin.json`. This file contains required fields such as the plugin name, version, description, and interface specifications that the Codex runtime uses to load and execute the plugin.

### How does the repository handle plugin discovery and categorization?

The repository maintains two marketplace definition files at [`/.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main//.agents/plugins/marketplace.json) and [`/.agents/plugins/api_marketplace.json`](https://github.com/openai/plugins/blob/main//.agents/plugins/api_marketplace.json). These JSON files enumerate all available plugins, including their filesystem paths, installation policies, and category assignments. The files regenerate automatically when new plugins are added to the `plugins/` directory.

### What optional components can a plugin include beyond the mandatory manifest?

Beyond the required [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest, a plugin directory may contain [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) for native app connectors, [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) for Multi-Channel-Protocol configurations, an `assets/` folder for UI resources, a `skills/` directory for reusable functions, an `agents/` folder for YAML-defined agents, and a `tests/` directory for validation suites.

### How can developers scaffold a new plugin that conforms to the repository structure?

Developers can use the Python helper script located at [`/.agents/skills/plugin-creator/scripts/create_basic_plugin.py`](https://github.com/openai/plugins/blob/main//.agents/skills/plugin-creator/scripts/create_basic_plugin.py). This utility generates the standard directory layout and manifest template, ensuring the new plugin integrates correctly with the marketplace metadata system and follows the established naming conventions.