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

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 manifest file and optional assets such as skills/, agents/, or .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, 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 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 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:

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 – App-level UI configuration for rendering the plugin interface
• .mcp.json – MCP (Marketplace Component Package) metadata
• 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:

#!/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 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:

{
  "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:

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 describing its metadata and interface.
• Optional Assets: Plugins may include skills/, agents/, commands/, assets/, .app.json, .mcp.json, and hooks.json files.
• Registry Mapping: The .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 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 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, the system cannot recognize or load the plugin.

How does the marketplace registry locate plugin contents?

The marketplace registry in .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 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 for UI rendering and .mcp.json for marketplace metadata. The commands/ directory and hooks.json file may also be present to define CLI interfaces and lifecycle events.

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