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

> Understand the OpenAI plugin directory structure. Explore the monorepo layout, manifest files, static assets, and the skills folder for modular capabilities. Learn how plugins are organized.

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

---

**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`](https://github.com/openai/plugins/blob/main//.agents/skills/plugin-creator/SKILL.md)) and standard repository files like [`README.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/SKILL.md) file (e.g., [`plugins/box/skills/box/SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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:

```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, 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:

```bash

# 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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) or [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json)) that defines metadata and entry points.
- **Skills** are modular capabilities stored in `skills/<skill-name>/`, each containing documentation ([`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md)), agent configs ([`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) or [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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/`.