OpenAI Plugin Directory Structure: A Complete Guide to the Monorepo Layout

The OpenAI Plugins repository follows a monorepo pattern where every plugin lives under the top-level plugins/ directory, with each plugin containing a manifest file, optional static assets, and a skills/ folder that houses modular capabilities with their own agent configurations and documentation.

The openai/plugins repository organizes community and official plugins as a monorepo, ensuring consistent discoverability and standardized packaging. Understanding the OpenAI plugin directory structure is essential for developers building new integrations or extending existing capabilities, as every plugin follows the same conventions for manifests, skills, and assets.

Top-Level Repository Layout

The repository root contains the plugins/ directory, which serves as the container for all individual plugin implementations. Alongside this, you'll find internal tooling under .agents/ (such as the plugin-creator skill at /.agents/skills/plugin-creator/SKILL.md) and standard repository files like README.md and .gitignore.

The plugins/ directory contains self-contained subdirectories named after each plugin (e.g., box, finn, zotero). Each subdirectory represents a complete, deployable unit with its own configuration and code.

Individual Plugin Structure

Every plugin follows a predictable layout that separates metadata from implementation logic.

Plugin Manifest Files

The entry point for any plugin is its manifest file, which exists as either plugins/<name>/.codex-plugin/plugin.json (as seen in the Box plugin) or plugins/<name>/.app.json (as used by the Finn plugin). This JSON file serves as the single source of truth for the plugin's metadata, required fields, authentication configuration, and API endpoints.

Static Assets

Visual resources live in plugins/<name>/assets/, containing icons and logos (like app-icon.png) that the marketplace UI references directly. Keeping assets alongside the plugin code eliminates external lookup dependencies and ensures version consistency.

The Skills Architecture

Skills are the modular units that OpenAI agents invoke to perform specific tasks. Each plugin contains one or more skills under its skills/ directory.

Skill Documentation

Every skill folder contains a SKILL.md file (e.g., plugins/box/skills/box/SKILL.md) that provides human-readable descriptions of the capability, usage instructions, and expected behaviors. This documentation serves as the contract between the plugin author and the AI agent.

Agent Configuration

The agents/ subdirectory within each skill contains YAML configuration files (typically openai.yaml) that define the LLM parameters for executing that skill. These files specify the model (e.g., gpt-4o), temperature settings (often 0.2 for deterministic outputs), and system prompts that shape the agent's behavior.

Reference Materials

External documentation, API specifications, and troubleshooting guides reside in references/ (e.g., plugins/box/skills/box/references/webhooks-and-events.md). These markdown files provide contextual knowledge that agents can consult during execution.

Helper Scripts

Executable logic lives in scripts/, typically containing Python modules like box_rest.py that handle external API communication. These scripts bridge the gap between the agent's reasoning and third-party service implementations.

Working with the Directory Structure

Below are practical patterns for interacting with the repository layout programmatically.

Loading a plugin manifest:

import json
from pathlib import Path

def load_manifest(plugin_name: str) -> dict:
    manifest_path = Path("plugins") / plugin_name / ".codex-plugin" / "plugin.json"
    return json.loads(manifest_path.read_text())

# Example: load the Box plugin manifest

box_manifest = load_manifest("box")
print(box_manifest["name"])  # → "Box"

Reading agent configuration:

import yaml
from pathlib import Path

def load_agent(plugin, skill):
    path = Path("plugins") / plugin / "skills" / skill / "agents" / "openai.yaml"
    return yaml.safe_load(path.read_text())

box_agent = load_agent("box", "box")
print(box_agent["model"])   # → gpt-4o

Executing helper scripts:

# Run the Box REST helper script

python plugins/box/skills/box/scripts/box_rest.py list_folders --path "/"

Summary

• The OpenAI plugin directory structure uses a monorepo pattern with all plugins under the top-level plugins/ folder.
• Each plugin requires a manifest file (.codex-plugin/plugin.json or .app.json) that defines metadata and entry points.
• Skills are modular capabilities stored in skills/<skill-name>/, each containing documentation (SKILL.md), agent configs (agents/openai.yaml), references, and scripts.
• Static assets are co-located in assets/ to ensure the marketplace UI can access icons without external lookups.
• The repository includes internal tooling under .agents/ for plugin creation and maintenance.

Frequently Asked Questions

What file defines an OpenAI plugin's capabilities?

The plugin manifest—located at either .codex-plugin/plugin.json or .app.json in the plugin root—defines the plugin's metadata, authentication requirements, and available endpoints. This JSON file serves as the discovery mechanism for the plugin system.

How are skills organized within an OpenAI plugin?

Each skill resides in its own subdirectory under plugins/<plugin-name>/skills/, containing a SKILL.md description, an agents/ folder with YAML configuration files, optional references/ for documentation, and scripts/ for executable helper code. This modular approach allows agents to load only the specific capabilities they need.

Where are agent configurations stored in the OpenAI plugins repository?

Agent configurations are stored at plugins/<plugin-name>/skills/<skill-name>/agents/openai.yaml, specifying the model (e.g., gpt-4o), temperature, and system prompts that control the LLM's behavior when executing that specific skill.

What is the purpose of the .agents/ directory at the repository root?

The .agents/ directory contains internal tooling and maintenance agents (such as the plugin-creator skill) used by the repository maintainers, distinct from the public plugins catalog that lives under plugins/.

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