# What Is the openai/plugins Repository? A Complete Guide to Codex Plugin Architecture

> Explore the openai/plugins repository a guide to Codex plugin architecture Learn to build package and distribute extensions using a declarative JSON driven approach

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

---

**The openai/plugins repository is a curated collection of Codex plugin examples that demonstrates how to create, package, and distribute functional extensions for the Codex platform using a declarative, JSON-driven architecture.**

The **openai/plugins** repository serves as the official reference implementation for developers building extensions for OpenAI's Codex platform. It contains production-ready examples such as Figma and Zotero integrations, showcasing exactly how to structure plugin manifests, define marketplace metadata in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json), and implement functional behaviors in the `skills/` directories. Mastering this repository is essential for anyone looking to extend Codex capabilities with custom tools that integrate seamlessly into the ecosystem.

## Core Architecture of the openai/plugins Repository

The repository follows a **declarative, data‑driven model** where JSON configuration files define the plugin catalog and runtime behavior, while the actual executable code resides in isolated `skills/` directories. This separation enables Codex to discover, install, and execute new plugins without requiring additional build steps or compilation.

### Repository Structure and Key Directories

Every plugin in the **openai/plugins** repository lives under `plugins/<name>/` and adheres to a strict organizational convention:

- **[`README.md`](https://github.com/openai/plugins/blob/main/README.md)** — Provides a high‑level overview of the repository and highlights featured example plugins.
- **`plugins/<name>/`** — Contains the complete source for an individual plugin.
- **[`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)** — The mandatory manifest describing metadata, interface capabilities, and skill locations.
- **`skills/`** — Houses the functional implementation files (typically Python scripts) that execute when the plugin is invoked.
- **[`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)** — Maps the plugin name to an internal connector ID used by the Codex runtime.
- **[`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json)** — The master registry that surfaces plugins to Codex users, defining installation policies, authentication modes, and categorization.

### The Plugin Manifest System

The **[`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)** file serves as the single source of truth for each extension. Located at `plugins/<name>/.codex-plugin/plugin.json`, it declares:

- **Metadata**: `name`, `version`, `description`, `author`, and `keywords`.
- **Interface block**: Supplies the `displayName`, `shortDescription`, `longDescription`, **capabilities** (Read/Write/Interactive), branding colors, and default prompts.
- **Asset locations**: Paths to `skills/`, [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), and optional hooks or agents.

Complementing this is **[`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)**, a lightweight mapping file that connects the plugin name to its runtime connector ID. For example, in [`plugins/figma/.app.json`](https://github.com/openai/plugins/blob/main/plugins/figma/.app.json), this mapping allows the Codex engine to route requests to the correct handler without parsing the full manifest.

### Skills and Functional Implementation

The actual logic resides in the **`skills/`** directory, containing executable scripts written in languages supported by the Codex runtime (primarily Python). These files implement the functional behavior exposed through the manifest. For instance, [`plugins/zotero/skills/zotero/scripts/zotero.py`](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/scripts/zotero.py) contains the API integration code that executes when users invoke Zotero-related commands.

## How Plugin Discovery Works in openai/plugins

The **marketplace discovery mechanism** centers on [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json). This JSON file enumerates every available plugin with strict policy controls:

- **Installation policy**: Defines availability status (e.g., `AVAILABLE`).
- **Authentication mode**: Specifies when credentials are requested (`ON_INSTALL`, `ON_USE`, etc.).
- **Categorization**: Groups plugins into functional domains such as *Creativity*, *Productivity*, *Developer Tools*, *Finance*, and *Security*.

When the Codex platform initializes, it parses this marketplace definition to populate the user interface, filter capabilities, and enforce security boundaries before downloading any plugin code.

## Working with the openai/plugins Repository: Code Examples

Developers can programmatically interact with the repository structure to load manifests, enumerate plugins, or import skills dynamically.

### Loading a Plugin Manifest Programmatically

To read a specific plugin's configuration, parse the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) file directly:

```python
import json
from pathlib import Path

def load_manifest(plugin_name: str) -> dict:
    """Read the 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)

figma_manifest = load_manifest("figma")
print(figma_manifest["interface"]["displayName"])

# → Figma

```

This approach accesses the metadata defined in the interface block, including display names and capability flags.

### Enumerating Available Plugins from the Marketplace

To discover all published plugins and their categories:

```python
import json

def list_plugins():
    with open(".agents/plugins/marketplace.json") as f:
        marketplace = json.load(f)
    for entry in marketplace["plugins"]:
        name = entry["name"]
        category = entry.get("category", "Uncategorized")
        print(f"{name:20} – {category}")

list_plugins()

```

This script reads the centralized marketplace definition, extracting installation policies and categorization data for each entry.

### Accessing Plugin Skills Dynamically

For advanced integrations, load skill modules programmatically by resolving their filesystem paths:

```python
from importlib import import_module
import pathlib

def load_skill(plugin_name: str, skill_path: str):
    # Resolve the absolute path of the skill script

    skill_file = pathlib.Path("plugins") / plugin_name / "skills" / skill_path
    # Convert file system path to a module import path

    module_name = ".".join(skill_file.with_suffix("").parts)
    return import_module(module_name)

# Example: load the Zotero API helper

zotero = load_skill("zotero", "zotero/scripts/zotero.py")
print(zotero.__doc__)  # prints the module docstring if present

```

This technique allows runtime inspection of the Python implementations located in `plugins/<name>/skills/` without manual import statements.

## Key Files and Their Roles

Understanding the **openai/plugins** repository requires familiarity with these critical paths:

- **[`README.md`](https://github.com/openai/plugins/blob/main/README.md)** — Repository overview and highlighted plugin examples.
- **[`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json)** — Master registry controlling plugin visibility, authentication modes, and installation policies.
- **`plugins/<name>/.codex-plugin/plugin.json`** — Per‑plugin manifest defining metadata, interface capabilities, and skill locations.
- **`plugins/<name>/.app.json`** — Connector mapping that links plugin names to runtime IDs.
- **`plugins/<name>/skills/…`** — Implementation directories containing executable scripts (e.g., [`plugins/zotero/skills/zotero/scripts/zotero.py`](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/scripts/zotero.py)).

## Summary

- The **openai/plugins** repository provides reference implementations for Codex extensions using a declarative JSON architecture.
- Each plugin requires a **[`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)** manifest in `.codex-plugin/` and an **[`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)** connector file to function within the ecosystem.
- The **`.agents/plugins/mark