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

> Understand how OpenAI's Codex plugins are organized within the plugins directory. Explore self-contained modules, plugin.json metadata, and skill-specific subdirectories for seamless integration.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: architecture
- Published: 2026-09-12

---

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

### Skill Subdirectories

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

- **[`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md)**: The primary documentation defining the skill's purpose, triggers, and conversational flow.
- **`agents/`**: YAML files (e.g., [`openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) and [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugin.json) files:

```python
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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.app.json) and [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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.