How the OpenAI Plugins Repository Is Organized: Directory Structure Explained

The OpenAI plugins repository follows a hierarchical, self-describing catalog structure where a top-level marketplace JSON registry points to individual plugin directories, each containing a mandatory manifest, modular skill definitions, and static assets.

The openai/plugins repository serves as the official reference implementation for Codex plugins, hosting a curated collection of community and official integrations. Understanding how this OpenAI plugins repository is organized is essential for developers building custom integrations or contributing to the ecosystem. The layout separates catalog metadata from plugin-specific implementation details, enabling Codex to discover and load capabilities declaratively without executing arbitrary code.

Top-Level Repository Structure

At the root of the repository, four primary elements define the catalog boundary:

• README.md – Human-readable introduction, usage notes, and a highlight list of featured plugins.
• .agents/ – Contains marketplace definitions and helper files used by Codex when loading plugins.
• plugins/ – Root directory for every individual plugin, with each sub-folder following the same internal contract.
• .git/, .gitignore – Standard Git metadata (not part of the plugin execution model).

This separation ensures that Codex can parse the entire catalog by reading only the JSON registry and specific plugin manifests, never needing to execute untrusted code during discovery.

The Marketplace Registry

Located at .agents/plugins/marketplace.json, this file acts as the single source of truth for the catalog that Codex queries at runtime.

Each entry in the marketplace JSON records:

• name – The short identifier used in prompts (e.g., @zotero, @github).
• source.path – The relative path to the plugin root (e.g., ./plugins/zotero).
• policy – Installation constraints and authentication requirements.
• category – High-level grouping such as "Productivity", "Developer Tools", or "Education & Research".

When Codex initializes, it reads this registry to determine which plugins are available and where to locate their manifests.

Individual Plugin Layout

Every plugin lives under plugins/<name>/ and follows an identical scaffold:

plugins/
└─ <name>/
   ├─ .codex-plugin/
   │   └─ plugin.json          ← core manifest (name, version, interface, etc.)
   ├─ assets/                  ← icons, screenshots, static files
   ├─ skills/
   │   ├─ <skill-name>/
   │   │   ├─ SKILL.md          ← markdown description of the skill
   │   │   ├─ agents/
   │   │   │   └─ openai.yaml   ← LLM prompt configuration
   │   │   └─ references/       ← optional docs, examples, API specs
   │   └─ …                     ← more skills
   ├─ .app.json                ← (optional) app-level metadata
   └─ .mcp.json                ← (optional) MCP configuration

The Plugin Manifest

The file plugins/<name>/.codex-plugin/plugin.json is mandatory and describes the plugin's UI, capabilities, and default prompts. For example, the Zotero plugin manifest at plugins/zotero/.codex-plugin/plugin.json contains:

{
  "name": "zotero",
  "version": "0.1.2",
  "description": "Work with Zotero from Codex…",
  "interface": {
    "displayName": "Zotero",
    "shortDescription": "Find papers and add citations",
    "category": "Education & Research",
    "capabilities": ["Interactive", "Read", "Write"]
  },
  "skills": "./skills/"
}

This declarative approach allows Codex to render UI elements and validate permissions before invoking any functionality.

Skills Directory Structure

The skills/ directory contains one or more sub-folders, each representing a distinct functional area (e.g., search, export, import). Inside each skill, three components define the behavior:

1. SKILL.md – Narrative documentation explaining the skill's purpose and usage patterns.
2. agents/openai.yaml – Configuration telling Codex how to translate user requests into structured prompts.
3. references/ – Supplemental material such as API spec snippets, code samples, or UI screenshots.

For the Zotero plugin, the skill specification at plugins/zotero/skills/zotero/agents/openai.yaml includes:

model: gpt-4
system_prompt: |
  You are a helpful assistant that can query a Zotero library.
  ...
examples:
  - user: "@Zotero find papers about transformers"
    assistant: |
      Search the local library for entries containing “transformers”.

Assets and Optional Configuration

The assets/ directory stores UI icons and screenshots referenced by the manifest fields composerIcon, logo, and screenshots. For example, the Zotero plugin icon resides at plugins/zotero/skills/zotero/assets/icon.png.

Two optional files augment plugin behavior:

• .app.json – Provides additional metadata (e.g., default authentication handlers) when a plugin is installed as an app rather than a pure skill set.
• .mcp.json – MCP (Marketplace Connector Protocol) configuration used by Codex's internal marketplace service.

Programmatically Accessing Repository Data

You can interact with the OpenAI plugins repository structure directly via HTTP requests to GitHub's raw content API.

Listing All Published Plugins (Python)

import json
import requests

# Load the marketplace definition directly from GitHub

URL = "https://raw.githubusercontent.com/openai/plugins/main/.agents/plugins/marketplace.json"
marketplace = json.loads(requests.get(URL).text)

# Print name and category for each plugin

for p in marketplace["plugins"]:
    print(f"{p['name']:20} – {p['category']}")

Output:

linear               – Productivity
atlassian-rovo       – Productivity
google-calendar      – Productivity
gmail                – Communication
slack                – Communication
zotero               – Education & Research

Loading a Single Plugin Manifest (Node.js)

const fetch = require('node-fetch');

async function loadManifest(name) {
  const url = `https://raw.githubusercontent.com/openai/plugins/main/plugins/${name}/.codex-plugin/plugin.json`;
  const resp = await fetch(url);
  const manifest = await resp.json();
  console.log(`${manifest.interface.displayName}: ${manifest.interface.shortDescription}`);
}

// Example: show Zotero's description
loadManifest('zotero');

Summary

• The OpenAI plugins repository uses a two-tier hierarchy: a central marketplace registry at .agents/plugins/marketplace.json and individual plugin directories under plugins/<name>/.
• Each plugin must contain a plugin.json manifest at .codex-plugin/plugin.json defining capabilities, version, and interface metadata.
• Functional capabilities are modularized into skills/ subdirectories, each containing documentation (SKILL.md), prompt engineering specs (agents/openai.yaml), and optional reference materials.
• Static assets (icons, screenshots) reside in assets/, while optional .app.json and .mcp.json files support advanced deployment scenarios.
• This declarative structure enables Codex to discover, validate, and execute plugins without running arbitrary code during the discovery phase.

Frequently Asked Questions

What is the purpose of the marketplace.json file in the OpenAI plugins repository?

The .agents/plugins/marketplace.json file serves as the single source of truth for the Codex plugin catalog. It lists every published plugin with metadata including the plugin name, source path, installation policy, and category. Codex queries this file at runtime to discover available plugins and determine where to locate their individual manifests.

Where is the main configuration file located for a specific plugin?

Each plugin's core configuration resides at plugins/<name>/.codex-plugin/plugin.json. This manifest is mandatory and contains the plugin's version, description, interface settings (display name, category, capabilities), and a reference to the skills directory. Without this file, Codex cannot load or display the plugin.

What files are required inside a plugin's skills directory?

Every skill subdirectory must contain at least two files: SKILL.md, which provides human-readable documentation describing the skill's functionality, and agents/openai.yaml, which contains the LLM prompt configuration that tells Codex how to translate user requests into structured actions. An optional references/ folder may contain supplemental API specs or code examples.

How does the repository handle plugin assets like icons and images?

Static assets such as icons, logos, and screenshots are stored in the assets/ directory within each plugin folder. The plugin.json manifest references these files through fields like composerIcon, logo, and screenshots, allowing Codex to render the plugin's UI elements without executing code.

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