OpenAI Plugins Repository Directory Structure: Complete Guide to the Monorepo Layout

The openai/plugins repository organizes every plugin as a self-contained package under a top-level plugins/ directory, with each plugin following a standardized layout that includes a manifest file, optional assets, and a modular skills/ subdirectory containing agent configurations and documentation.

The openai/plugins repository serves as a centralized monorepo for community and official OpenAI plugins. Its directory structure enforces consistency across all plugins while separating public capabilities from internal tooling. Whether you are contributing a new integration or debugging an existing skill, understanding this folder hierarchy is essential for navigating the codebase effectively.

Top-Level Directory Organization

The root of the repository contains three primary categories: the plugins/ container, internal tooling under .agents/, and standard repository metadata.

• plugins/: The central container holding every individual plugin as a separate subdirectory (e.g., zotero, finn, box). Each subfolder represents a standalone plugin package.
• .agents/: Houses internal utility skills used for repository maintenance, such as the plugin-creator skill, which are not exposed in the public plugin catalog.
• Root configuration files: Standard Git and project files including README.md (contribution guidelines and overview) and .gitignore (excluding credentials and generated files).

Individual Plugin Structure

Every plugin within plugins/<plugin-name>/ follows a predictable scaffolding that separates metadata, visual assets, and functional capabilities.

Plugin Manifests

Each plugin defines its metadata and entry points through a manifest file located in either .codex-plugin/plugin.json or .app.json (legacy format). For example, the Box plugin uses plugins/box/.codex-plugin/plugin.json, while the Finn plugin uses plugins/finn/.app.json. These JSON files specify the plugin name, authentication requirements, and available endpoints.

Assets Directory

The optional assets/ subdirectory stores static visual resources such as icons and logos. The marketplace UI references these files directly when displaying plugin listings. For instance, plugins/box/assets/app-icon.png provides the visual identity for the Box integration.

Skills Subdirectory

The skills/ folder contains one or more capability modules that define the plugin's behavior. Each skill resides in its own folder (e.g., plugins/box/skills/box/) and includes:

• SKILL.md: Human-readable documentation describing the skill's purpose and usage.
• agents/openai.yaml: Configuration for the OpenAI agent, specifying the model (e.g., gpt-4o), temperature, and system prompts.
• references/: Markdown files containing external API documentation, specifications, or troubleshooting guides.
• scripts/: Optional Python helper scripts that the skill invokes for external API communication, such as plugins/box/skills/box/scripts/box_rest.py.

Programmatically Navigating the Repository

You can interact with the openai/plugins directory structure using standard file I/O operations to load manifests, parse agent configurations, or execute helper scripts.

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: str, skill: str) -> dict:
    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 Skill Scripts

# Run the Box REST helper script

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

Summary

• The monorepo structure places all plugins under a unified plugins/ directory, with each plugin acting as an isolated package.
• Manifest files (.codex-plugin/plugin.json or .app.json) serve as the single source of truth for plugin metadata and authentication.
• The skills/ subdirectory modularizes capabilities, bundling agent configurations (agents/openai.yaml), documentation (SKILL.md), and executable scripts.
• Assets are colocated with plugins in assets/ to facilitate marketplace integration without external lookups.
• Internal tooling resides in .agents/, separate from the public plugin catalog.

Frequently Asked Questions

What is the difference between .codex-plugin/plugin.json and .app.json manifests?

Both files serve the same purpose of defining plugin metadata, but .codex-plugin/plugin.json represents the current standard format, while .app.json is a legacy location used by older plugins like Finn. New contributions should use the .codex-plugin/plugin.json path.

How does the skills/ directory structure work within a plugin?

The skills/ directory contains modular capability units that OpenAI agents invoke. Each skill folder includes a SKILL.md description, an agents/ subdirectory with YAML configuration files defining LLM parameters, a references/ folder for documentation, and an optional scripts/ folder for helper utilities.

Where are visual assets stored in the openai/plugins repository?

Visual assets such as icons and logos are stored in the plugins/<plugin-name>/assets/ directory. This colocation ensures the marketplace UI can retrieve plugin branding without requiring external URL lookups or complex path resolution.

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

The .agents/ directory contains internal utility skills, such as plugin-creator, used for maintaining and scaffolding new plugins within the repository. These tools are not part of the public plugin catalog and are intended for repository contributors rather than end users.

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