# How the OpenAI Plugins Repository Is Organized: Directory Structure Explained

> Understand the openai/plugins repository structure. Discover how a marketplace JSON registry connects to individual plugin directories, each with a manifest, skill definitions, and assets.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: internals
- Published: 2026-06-24

---

**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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/zotero/.codex-plugin/plugin.json) contains:

```json
{
  "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`](https://github.com/openai/plugins/blob/main/SKILL.md)** – Narrative documentation explaining the skill's purpose and usage patterns.
2. **[`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/agents/openai.yaml) includes:

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

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

```javascript
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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) and individual plugin directories under `plugins/<name>/`.
- Each plugin must contain a **[`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json)** manifest at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) defining capabilities, version, and interface metadata.
- Functional capabilities are modularized into **`skills/`** subdirectories, each containing documentation ([`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md)), prompt engineering specs ([`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml)), and optional reference materials.
- Static assets (icons, screenshots) reside in **`assets/`**, while optional **[`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)** and **[`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/SKILL.md), which provides human-readable documentation describing the skill's functionality, and [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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.