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

> Explore the openai/plugins repository directory structure. Understand the monorepo layout featuring standardized plugin packages, manifest files, and modular skills subdirectories.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: deep-dive
- Published: 2026-07-03

---

**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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) or [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) (legacy format). For example, the Box plugin uses [`plugins/box/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/box/.codex-plugin/plugin.json), while the Finn plugin uses [`plugins/finn/.app.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md)**: Human-readable documentation describing the skill's purpose and usage.
- **[`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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

```python
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

```python
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

```bash

# 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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) or [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/agents/openai.yaml)), documentation ([`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) and [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) manifests?

Both files serve the same purpose of defining plugin metadata, but [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) represents the current standard format, while [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) is a legacy location used by older plugins like Finn. New contributions should use the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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.