# Where Are the Plugin Contents Located in the OpenAI Plugins Repository?

> Discover where plugin contents are stored in the openai plugins repository. Find plugin files organized within the plugins/ directory, each with a plugin.json manifest.

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

---

**All plugin contents in the openai/plugins repository reside under the top-level `plugins/` directory, with each plugin isolated in its own subfolder containing a mandatory [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest file and optional assets such as `skills/`, `agents/`, or [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) configurations.**

The openai/plugins repository organizes extensible capabilities through a strict directory convention that separates individual plugin packages. Understanding exactly where these plugin contents are located is essential for developers integrating with the Codex ecosystem or contributing new automation tools.

## The Top-Level `plugins/` Directory Structure

The repository anchors all plugin contents under a single **`plugins/`** directory at the repository root. Each individual plugin lives in its own sub-folder named after the plugin identifier, such as `plugins/outlook-calendar` or `plugins/magicpath`.

According to the repository's [`README.md`](https://github.com/openai/plugins/blob/main/README.md), this layout follows a consistent convention where every plugin directory contains the required manifest and optional companion surfaces. The marketplace definition in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) confirms this structure by mapping plugin names to local paths using the `"path": "./plugins/<plugin-name>"` property. For example, the Outlook-Calendar entry specifies `"path": "./plugins/outlook-calendar"` to locate its contents.

## Mandatory Plugin Manifest Files

Every plugin directory must contain a **[`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)** file that serves as the core manifest. This file describes the plugin's name, version, interface definitions, and other metadata required for registration.

You can load this manifest programmatically to inspect plugin metadata:

```python
import json
from pathlib import Path

def load_manifest(plugin_name):
    manifest_path = Path("plugins") / plugin_name / ".codex-plugin" / "plugin.json"
    with manifest_path.open() as f:
        return json.load(f)

print(load_manifest("outlook-calendar"))

```

This Python function constructs the path `plugins/<name>/.codex-plugin/plugin.json` and returns the parsed JSON object, allowing you to access the plugin's interface definitions programmatically.

## Optional Plugin Assets and Configuration

Beyond the mandatory manifest, plugin folders may contain optional directories and configuration files that extend functionality:

- **`skills/`** – Reusable skill definitions used by the plugin's automation logic
- **`agents/`** – Agent-specific prompts and configuration files
- **`commands/`** – CLI command definitions and associated handlers
- **`assets/`** – Media files such as icons and screenshots referenced by the manifest
- **[`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)** – App-level UI configuration for rendering the plugin interface
- **[`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json)** – MCP (Marketplace Component Package) metadata
- **[`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json)** – Event hook definitions for lifecycle management

To discover which optional assets a specific plugin includes, use a script that checks for the presence of these paths:

```bash
#!/usr/bin/env bash
PLUGIN="magicpath"
BASE="plugins/$PLUGIN"

echo "=== $PLUGIN ==="
[[ -d "$BASE/skills" ]] && echo "Skills: $(ls $BASE/skills)"
[[ -f "$BASE/.app.json" ]] && echo "App config present"
[[ -d "$BASE/assets" ]] && echo "Assets: $(ls $BASE/assets)"

```

## Marketplace Registry and Path Resolution

The repository uses [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) as the central registry that points to each plugin's location. This JSON file contains entries linking plugin names to their respective directories under the `plugins/` folder.

A typical entry follows this structure:

```json
{
  "name": "outlook-calendar",
  "source": { "source": "local", "path": "./plugins/outlook-calendar" }
}

```

As implemented in openai/plugins, this registry allows the system to resolve plugin locations dynamically without hardcoding paths throughout the codebase.

## Programmatic Discovery of Plugin Contents

To enumerate all available plugins in the repository, traverse the `plugins/` directory and filter for subdirectories:

```javascript
import { readdir } from "fs/promises";
import path from "path";

async function listPlugins() {
  const pluginsRoot = path.resolve("plugins");
  const entries = await readdir(pluginsRoot, { withFileTypes: true });
  const plugins = entries.filter(e => e.isDirectory()).map(e => e.name);
  console.log("Available plugins:", plugins);
}

listPlugins();

```

This Node.js script reads the `plugins/` directory and returns an array of plugin names corresponding to each subfolder, effectively mapping the physical directory structure to available plugin identifiers.

## Summary

- **Root Location**: All plugin contents are stored under the top-level `plugins/` directory in the repository root.
- **Manifest Requirement**: Each plugin must contain [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) describing its metadata and interface.
- **Optional Assets**: Plugins may include `skills/`, `agents/`, `commands/`, `assets/`, [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json), and [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) files.
- **Registry Mapping**: The [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) file references each plugin using relative paths like `./plugins/<plugin-name>`.
- **Consistency**: The structure is enforced by the repository [`README.md`](https://github.com/openai/plugins/blob/main/README.md) and validated through the marketplace registry configuration.

## Frequently Asked Questions

### What is the mandatory file structure for each plugin in the openai/plugins repository?

Every plugin must reside in its own directory under `plugins/<name>/` and contain a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest file. This JSON file defines the plugin's name, version, and interface specifications. Without this manifest file in the exact location [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json), the system cannot recognize or load the plugin.

### How does the marketplace registry locate plugin contents?

The marketplace registry in [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) uses a `"source"` object with a `"path"` property that points to `"./plugins/<plugin-name>"`. This relative path mapping allows the system to resolve the physical location of each plugin's contents dynamically, ensuring that the registry stays synchronized with the actual directory structure.

### Can a plugin exist outside the `plugins/` directory?

No, according to the repository structure defined in the [`README.md`](https://github.com/openai/plugins/blob/main/README.md) and enforced by the marketplace configuration, all plugin contents must be anchored under the `plugins/` directory. The registry explicitly references paths using the `./plugins/` prefix, and discovery scripts expect this layout when scanning for available plugins.

### What optional assets are commonly found in plugin directories beyond the manifest?

Common optional assets include the `skills/` directory for reusable automation definitions, the `agents/` directory for prompt configurations, `assets/` for media files, and configuration files like [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) for UI rendering and [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) for marketplace metadata. The `commands/` directory and [`hooks.json`](https://github.com/openai/plugins/blob/main/hooks.json) file may also be present to define CLI interfaces and lifecycle events.