# OpenAI Plugins Repository: 7 Architectural Patterns for Modular AI Systems

> Explore 7 architectural patterns from the OpenAI plugins repository. Discover how manifest-driven design enables modular AI systems with dynamic discovery and policy-enforced execution.

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

---

**The OpenAI plugins repository implements a manifest-driven architecture where self-contained plugins declare capabilities through JSON manifests and YAML agents, enabling dynamic discovery and policy-enforced execution without modifying core platform code.**

The OpenAI plugins repository serves as a reference implementation for building extensible AI platforms that integrate external APIs through strict declarative contracts. As implemented in the openai/plugins codebase, this architecture isolates functionality into discrete, self-describing units discovered through a centralized marketplace configuration, providing a blueprint for designing plugin systems that balance flexibility with automated security enforcement.

## Manifest-Driven Plugin Structure

The foundation of the repository relies on a **manifest-first pattern** that requires every plugin to declare its metadata, capabilities, and dependencies through standardized configuration files. Each plugin resides in a dedicated folder under `plugins/` containing three critical JSON manifests.

### Core Configuration Files

The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file functions as the primary descriptor, defining the plugin's `name`, `version`, `description`, `category`, and policy links. For example, the Gmail plugin's manifest at [`plugins/gmail/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/gmail/.codex-plugin/plugin.json) specifies the display metadata and routing information the Codex runtime uses during initialization.

Adjacent to the core manifest, the [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) file defines the **app connector**—the OAuth scopes, API endpoints, and credential requirements necessary to communicate with the external service. The optional [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) (Multi-Competency Profile) provides marketplace UI metadata used by the Codex interface for categorization and display purposes.

### Skill and Agent Organization

Beneath these manifests, the `skills/` directory contains isolated, task-oriented scripts implementing specific capabilities. Each skill subdirectory includes:

- A [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file documenting the input/output schema
- Executable scripts (typically Python) performing the actual API operations
- An `agents/` subdirectory containing YAML prompt templates

For instance, [`plugins/gmail/skills/gmail/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/gmail/skills/gmail/agents/openai.yaml) contains the LLM prompt templates that shape how the model interacts with Gmail-specific operations, while `plugins/gmail/skills/gmail/scripts/` houses the executable Python modules.

## Centralized Marketplace Configuration

Plugin discovery operates through a single source of truth: [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json). This JSON document enumerates all available plugins—whether local or remote—enabling the Codex UI to render the plugin picker without scanning the filesystem dynamically.

Each entry in the marketplace follows a strict schema:

```json
{
  "name": "gmail",
  "source": { "source": "local", "path": "./plugins/gmail" },
  "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
  "category": "Communication"
}

```

Because the marketplace is a **plain JSON document**, adding new plugins requires only appending an entry; no code changes or redeployment of the core platform is necessary. The runtime references this file during initialization to build the available capability graph.

## Policy-Based Security Boundaries

Every marketplace entry includes a `policy` object that enforces security boundaries without custom authorization code. These policies govern two critical dimensions:

**Installation Policy** controls visibility and availability. Values like `AVAILABLE` indicate immediate access, while alternative states can require explicit user installation or hide plugins entirely.

**Authentication Policy** determines credential timing. The `ON_INSTALL` value requires users to complete OAuth flows before accessing the plugin, whereas `ON_USE` defers authentication until the first skill invocation. The Codex runtime reads these policies automatically to enforce security boundaries during the execution lifecycle.

## Skill-Based Execution Model

The runtime follows a **three-step execution flow** that separates LLM interaction from operational logic:

1. **Prompt Generation**: The system renders the `agents/*.yaml` template with user context, producing a structured query for the LLM.
2. **Skill Invocation**: The LLM generates parameters that trigger the associated script through a standardized interface, typically invoking a `run(task_input: dict)` function in Python modules.
3. **Result Normalization**: Scripts return JSON complying with the output schema defined in [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md), ensuring consistent handling regardless of the underlying API's response format.

Skills remain **stateless and versioned** alongside their parent plugin, enabling reuse across multiple integrations. For example, a generic REST request skill might serve multiple life-science plugins without code duplication.

## External Plugin Integration

The marketplace supports **dynamic inclusion** of third-party code through URL-based sources, enabling plugin distribution without copying code into the main repository:

```json
{
  "source": { "source": "url", "url": "https://github.com/CrowdStrike/foundry-skills.git" }
}

```

This pattern allows external contributors to maintain their own skill packs while the platform enforces the same policy and security models defined in the central marketplace configuration.

## Developer Tooling and Scaffolding

To ensure architectural consistency, the repository includes automation tools under `.agents/skills/plugin-creator/`. The [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) script generates compliant skeleton structures, validating that new plugins contain required manifests, skill directories, and documentation templates before they can be registered in the marketplace.

## Documentation-First Contracts

Every skill ships with a [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) file serving dual purposes: human-readable documentation and machine-readable schema validation. This file explicitly defines input parameters, output structures, and error conditions, acting as the source of truth for both developers and automated validation tools in the CI pipeline.

## Implementation Examples

### Loading Plugin Manifests

The following Python pattern demonstrates reading the canonical manifest structure:

```python
import json, pathlib

def load_plugin(name: str, base: pathlib.Path = pathlib.Path('.')):
    """Read a plugin's .codex-plugin/plugin.json and return the dict."""
    manifest_path = base / 'plugins' / name / '.codex-plugin' / 'plugin.json'
    with manifest_path.open() as f:
        return json.load(f)

gmail = load_plugin('gmail')
print(gmail['interface']['displayName'])   # → Gmail

```

### Executing Skill Scripts

Skill implementations follow a standardized interface receiving task input and returning structured data:

```python

# Simplified from plugins/gmail/skills/gmail/scripts/list_threads.py

import json, requests

def run(task_input: dict) -> dict:
    token = task_input['access_token']
    resp = requests.get(
        'https://gmail.googleapis.com/gmail/v1/users/me/threads',
        headers={'Authorization': f'Bearer {token}'}
    )
    data = resp.json()
    return {"threads": [t['id'] for t in data.get('threads', [])[:5]]}

```

The runtime invokes this `run()` function after populating `task_input` with validated OAuth tokens and user parameters derived from the LLM interaction.

### Registering New Plugins

To add a plugin to the ecosystem, append an entry to [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json):

```json
{
  "name": "my-awesome-plugin",
  "source": { "source": "local", "path": "./plugins/my-awesome-plugin" },
  "policy": { "installation": "AVAILABLE", "authentication": "ON_USE" },
  "category": "Productivity"
}

```

Once added, the plugin immediately appears in the Codex UI according to the specified policy constraints.

## Summary

- **Manifest-first architecture**: Every plugin declares capabilities through [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json), [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), and optional [`.mcp.json`](https://github.com/openai/plugins/blob/main/.mcp.json) files, enabling automated discovery without code inspection.
- **Centralized marketplace**: The [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) file acts as the single registry for all plugins, supporting both local paths and external URL sources.
- **Declarative security**: The `policy` object enforces installation and authentication constraints (`ON_INSTALL` vs `ON_USE`) without custom authorization logic.
- **Skill isolation**: Execution occurs through stateless, documented skills utilizing [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) schemas and `agents/*.yaml` prompt templates.
- **Standardized interfaces**: Skills implement consistent entry points like `run(task_input: dict)` and return JSON conforming to declared output schemas.
- **Tool-assisted compliance**: The [`create_basic_plugin.py`](https://github.com/openai/plugins/blob/main/create_basic_plugin.py) scaffolding tool ensures new plugins meet architectural requirements before marketplace registration.

## Frequently Asked Questions

### What is the purpose of the .codex-plugin/plugin.json file in the OpenAI plugins repository?

The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file serves as the canonical manifest declaring a plugin's metadata, including its display name, version, description, category, and links to app connectors. This file enables the Codex runtime to discover and initialize the plugin without executing custom code, as seen in [`plugins/gmail/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/gmail/.codex-plugin/plugin.json).

### How does the marketplace.json file manage plugin discovery?

The [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) file functions as a centralized registry enumerating all available plugins through JSON entries containing `name`, `source` (local path or URL), `policy`, and `category`. The Codex UI reads this file to populate the plugin picker, and the runtime uses it to resolve plugin locations and security policies during execution.

### What distinguishes ON_INSTALL from ON_USE authentication policies?

**ON_INSTALL** requires users to complete OAuth or credential validation immediately upon adding the plugin to their environment, blocking access until authentication succeeds. **ON_USE** delays this requirement until the first actual skill invocation, allowing users to browse plugin capabilities before granting API access. Both values are set in the `policy.authentication` field of the marketplace entry.

### How are skills executed within the OpenAI plugins architecture?

Skills execute through a three-phase process: first, the runtime renders prompt templates from `agents/*.yaml` to generate the LLM query; second, the LLM outputs parameters that trigger the skill's `run()` function (typically a Python script in `skills/{name}/scripts/`); third, the script returns normalized JSON conforming to the [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) schema, which the runtime delivers back to the user or subsequent processing steps.