OpenAI Plugins Repository: 7 Architectural Patterns for Modular AI Systems

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 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 specifies the display metadata and routing information the Codex runtime uses during initialization.

Adjacent to the core manifest, the .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 (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 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 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. 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:

{
  "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, 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:

{
  "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 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 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:

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:

# 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:

{
  "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, .app.json, and optional .mcp.json files, enabling automated discovery without code inspection.
• Centralized marketplace: The .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 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 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 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.

How does the marketplace.json file manage plugin discovery?

The .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 schema, which the runtime delivers back to the user or subsequent processing steps.

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