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

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, 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 — 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 — 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 — Maps the plugin name to an internal connector ID used by the Codex runtime.
• .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 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, and optional hooks or agents.

Complementing this is .app.json, a lightweight mapping file that connects the plugin name to its runtime connector ID. For example, in 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 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. 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 file directly:

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:

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:

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 — Repository overview and highlighted plugin examples.
• .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).

Summary

• The openai/plugins repository provides reference implementations for Codex extensions using a declarative JSON architecture.
• Each plugin requires a plugin.json manifest in .codex-plugin/ and an .app.json connector file to function within the ecosystem.
• The **`.agents/plugins/mark

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