How Plugins Are Organized in the Plugins Directory: OpenAI's Codex Plugin Architecture

Each integration in the openai/plugins repository is a self-contained module within the root plugins/ folder, anchored by a mandatory .codex-plugin/plugin.json metadata file and structured into skill-specific subdirectories that declare capabilities, agents, and assets.

The openai/plugins repository implements a declarative, file-based registry designed for the Codex Plugin framework. Understanding how plugins are organized in the plugins directory is essential for developers contributing new integrations or building tools that consume these conversational AI capabilities.

The Root Registry Pattern

The plugins/ directory at the repository root functions as a flat registry. Each immediate subdirectory represents one distinct plugin, enabling the Codex runtime to discover integrations by scanning for the presence of plugins/<plugin_name>/.codex-plugin/plugin.json.

This flat structure ensures that adding a new integration requires only creating a new folder that conforms to the established contract. The runtime does not require central registration files; instead, it walks the directory tree and loads capabilities dynamically from each plugin's metadata.

Core Metadata and Configuration Files

Every plugin must contain specific files that declare its identity and interface to the Codex runtime.

The plugin.json Manifest

The file plugins/<plugin>/.codex-plugin/plugin.json is the mandatory entry point. It contains the plugin name, version, author, description, and the public interface definition including display name, category, default prompts, branding URLs, and declared capabilities such as Read, Write, or Interactive.

Optional Application Configurations

Plugins may include additional configuration files depending on their integration requirements:

• .app.json: Located at plugins/<plugin>/.app.json, this file specifies application-level configuration required by the Codex runtime, including required OAuth scopes and authentication flow settings.
• .mcp.json: Found at plugins/<plugin>/.mcp.json, this optional file configures the Multi-Channel Protocol (MCP) server for plugins that expose backend services.
• README.md: A human-readable overview at plugins/<plugin>/README.md providing installation notes and usage examples.

Skill Packaging and Agent Definitions

Within each plugin, the skills/ directory contains one or more skill packages. Each skill represents a reusable conversational workflow documented by a SKILL.md file.

Skill Subdirectories

Individual skills reside in folders like plugins/<plugin>/skills/<skill_name>/. A skill package may include:

• SKILL.md: The primary documentation defining the skill's purpose, triggers, and conversational flow.
• agents/: YAML files (e.g., openai.yaml) that define OpenAI agent behavior and configuration for executing the skill.
• assets/: Icons, screenshots, or other UI resources specific to the skill interface.
• references/: Markdown files containing supporting documentation, API specifications, or example payloads.

Plugin-Level Assets

Plugins may also contain a top-level assets/ directory (e.g., plugins/<plugin>/assets/) for plugin-wide branding elements such as logos and composer icons used across all skills.

Real Examples from the OpenAI Plugins Repository

Examining concrete implementations illustrates how the directory structure scales across different integration types.

Canva Design Tools

The Canva plugin demonstrates a multi-skill architecture. Its metadata lives in plugins/canva/.codex-plugin/plugin.json, while individual capabilities like resizing, bulk creation, and editing reside in separate subdirectories under plugins/canva/skills/ (for example, canva-resize-for-social-media/). Each skill directory contains its own SKILL.md and agents/openai.yaml files. Branding assets are centralized in plugins/canva/assets/.

Codex Security Scans

The Codex Security plugin provides security-scan workflows. Its descriptor is located at plugins/codex-security/.codex-plugin/plugin.json, with skill implementations such as vulnerability-writeup and verify-fix nested under plugins/codex-security/skills/.

Cloudflare Wrangler

The Cloudflare integration organizes its Wrangler skill for managing Cloudflare resources using a nested structure. Its descriptor resides at plugins/cloudflare/skills/wrangler/.codex-plugin/plugin.json, demonstrating that metadata files can exist within skill directories for specific implementations.

ClickUp Task Management

ClickUp contains task-management capabilities with its top-level metadata in plugins/clickup/.codex-plugin/plugin.json and various skills distributed under plugins/clickup/skills/.

Programmatically Exploring Plugin Organization

You can enumerate and inspect the plugin structure using Python's pathlib module. The following script demonstrates how the Codex runtime discovers plugins by scanning for plugin.json files:

import json
import pathlib
from urllib.parse import quote

# Path to the repository root (adjust if run elsewhere)

repo_root = pathlib.Path("/cache/repos/github.com/openai/plugins/main")

def plugin_descriptor_path(plugin_name: str) -> pathlib.Path:
    """Return the absolute path to a plugin's plugin.json."""
    return repo_root / "plugins" / plugin_name / ".codex-plugin" / "plugin.json"

def list_plugins() -> list[str]:
    """Return a list of plugin directory names that contain a plugin.json."""
    plugins_dir = repo_root / "plugins"
    return [
        p.name for p in plugins_dir.iterdir() 
        if (p / ".codex-plugin" / "plugin.json").exists()
    ]

def load_plugin_metadata(name: str) -> dict:
    """Parse a plugin's JSON descriptor."""
    with plugin_descriptor_path(name).open() as f:
        return json.load(f)

# Example usage: List all plugins and their descriptions

for name in list_plugins():
    meta = load_plugin_metadata(name)
    print(f"{meta['name']} ({meta['version']}): {meta['interface']['shortDescription']}")
    gh_url = f"https://github.com/openai/plugins/blob/main/plugins/{quote(name)}/.codex-plugin/plugin.json"
    print(f"Metadata URL: {gh_url}\n")

This approach mirrors the discovery mechanism used by the Codex runtime, which validates the existence of .codex-plugin/plugin.json before loading declared capabilities.

Summary

• The plugins/ directory acts as a flat registry where each subdirectory is a self-contained integration discovered via the mandatory .codex-plugin/plugin.json file.
• Required structure includes a top-level metadata manifest and typically a skills/ directory containing documented workflows with agent definitions.
• Optional configurations such as .app.json and .mcp.json extend OAuth and backend protocol support without modifying core code.
• Real-world implementations like Canva and Codex Security demonstrate consistent organization with skill-specific subdirectories containing agents, assets, and references.
• Runtime discovery relies on filesystem scanning rather than central registries, enabling modular addition and removal of plugins without touching the core runtime.

Frequently Asked Questions

What is the minimum required file structure for a valid plugin?

A valid plugin requires only a single file: plugins/<plugin_name>/.codex-plugin/plugin.json. This JSON manifest must declare the plugin's name, version, and interface capabilities. While optional directories like skills/ and assets/ enhance functionality, the runtime recognizes a plugin solely by the presence of this metadata file.

How does the Codex runtime discover plugins in the directory?

The runtime discovers plugins by scanning the plugins/ directory for subdirectories containing .codex-plugin/plugin.json. It does not rely on a central index or configuration file; instead, it walks the filesystem at startup, validates each discovered manifest, and registers the declared capabilities dynamically.

Can a single plugin contain multiple skills?

Yes. Plugins commonly organize multiple related skills under their skills/ subdirectory. For example, the Canva plugin contains separate skills for resizing, bulk creation, and editing, each with its own SKILL.md and agent configurations, all registered under the single Canva plugin metadata.

What distinguishes plugin-level assets from skill-level assets?

Plugin-level assets reside in plugins/<plugin>/assets/ and typically contain branding elements like logos used across all skills in the plugin. Skill-level assets live within individual skill directories (e.g., plugins/<plugin>/skills/<skill>/assets/) and contain specific UI resources or screenshots relevant only to that particular conversational workflow.

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