What Is the OpenAI Plugins Repository? A Complete Guide to Codex Extensions

The OpenAI Plugins repository is a curated collection of Codex plugin examples that demonstrates how to extend the Codex runtime with new capabilities through standardized manifests and skill definitions.

The openai/plugins repository serves as the official reference implementation for integrating third-party services with OpenAI's Codex agent. It provides a modular framework for packaging, describing, and exposing external APIs—ranging from productivity tools like Airtable and Notion to payment platforms like Stripe—so that Codex agents can discover and invoke new functionality through a unified interface.

Core Architecture and Directory Structure

The repository follows a strict convention where each plugin resides under plugins/<name>/ and contains specific metadata files that define its capabilities and entry points.

The Plugin Manifest

Every plugin must contain a .codex-plugin/plugin.json file that describes the plugin's metadata, interface, and entry points. This manifest is required for Codex to recognize and load the extension.

According to the repository's README.md, the manifest specifies the plugin name, version, capabilities, and paths to skills and optional app configurations.

{
  "name": "my‑example",
  "version": "0.0.1",
  "description": "A simple example plugin",
  "interface": {
    "displayName": "My Example",
    "shortDescription": "Demo plugin for Codex",
    "capabilities": ["Read", "Write"]
  },
  "skills": "./skills/",
  "apps": "./.app.json"
}

The Marketplace Registry

The .agents/plugins/marketplace.json file acts as the default marketplace that maps logical plugin names to their local source directories. This registry controls installation policies and authentication requirements for each plugin.

To make a plugin discoverable by Codex, you append an entry to this marketplace configuration:

{
  "name": "my‑example",
  "source": {
    "source": "local",
    "path": "./plugins/my‑example"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

Skills and Asset Organization

Inside each plugin folder, the skills/ directory contains one or more skill definitions. Each skill consists of a SKILL.md file that describes the skill's behavior, input parameters, and output format. Plugins may also include:

• ./.app.json – Optional plugin-level app configuration
• ./assets/ – UI assets such as logos and icons
• ./agents/ – Optional agent definitions for custom execution logic

For example, the Airtable plugin includes skills/airtable-overview/SKILL.md which documents how Codex agents should interact with the Airtable API.

How Plugins Extend the Codex Runtime

Plugins extend Codex by exposing skills—discrete capabilities that agents can invoke through standardized function calls. When a Codex agent needs to perform an action provided by a plugin, it references the plugin name and skill identifier defined in the manifest.

The runtime loads the marketplace configuration at startup, discovers available plugins, and validates their manifests against the expected schema. When an agent calls a skill, Codex parses the SKILL.md documentation to understand parameter requirements and expected outputs.

Practical Implementation Examples

Creating a Minimal Plugin

To create a functional plugin in the OpenAI Plugins repository, you need three core components: a manifest, a marketplace entry, and at least one skill definition.

Step 1: Define the Plugin Manifest

Create .codex-plugin/plugin.json in your plugin directory:

{
  "name": "my‑example",
  "version": "0.0.1",
  "description": "A simple example plugin",
  "interface": {
    "displayName": "My Example",
    "shortDescription": "Demo plugin for Codex",
    "capabilities": ["Read", "Write"]
  },
  "skills": "./skills/",
  "apps": "./.app.json"
}

Step 2: Register in the Marketplace

Add your plugin to .agents/plugins/marketplace.json:

{
  "name": "my‑example",
  "source": {
    "source": "local",
    "path": "./plugins/my‑example"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

Step 3: Document Your Skills

Create skills/my-skill/SKILL.md to define the behavior:

# My Example Skill

## Description

Performs a simple echo of the provided input.

## Input

- `message` (string): Text to echo.

## Output

- `echoed` (string): Same text that was supplied.

## Implementation

The skill is implemented as a pure function that returns the input unchanged.

Step 4: Invoke from an Agent

Codex agents interact with plugins using the run_skill method:

# Assume the marketplace has been loaded and the plugin is installed

result = await codex.run_skill(
    plugin="my-example",
    skill="my-example-skill",
    input={"message": "Hello, world!"}
)
print(result["echoed"])  # → "Hello, world!"

Summary

The OpenAI Plugins repository provides a standardized framework for extending Codex with third-party integrations:

• Each plugin requires a manifest at .codex-plugin/plugin.json that defines metadata and capabilities
• The marketplace file at .agents/plugins/marketplace.json controls plugin discovery and installation policies
• Skills are documented in SKILL.md files within the skills/ directory, defining how agents interact with the functionality
• Agent invocation occurs through the run_skill method, which routes requests to the appropriate plugin based on the marketplace configuration

Frequently Asked Questions

What is the purpose of the plugin.json manifest file?

The .codex-plugin/plugin.json file serves as the mandatory entry point that describes the plugin's identity, version, capabilities, and skill locations. Codex uses this manifest to validate the plugin structure and determine which actions the plugin can perform.

How do I register a new plugin in the OpenAI Plugins repository?

To register a plugin, append a JSON object to .agents/plugins/marketplace.json that specifies the plugin name, local source path, installation policy, and authentication requirements. This entry enables Codex to discover and load the plugin from the plugins/<name>/ directory.

What is the difference between a plugin and a skill in Codex?

A plugin is the top-level container defined by a manifest that groups related capabilities, while a skill is a specific functionality documented in a SKILL.md file within the plugin's skills/ directory. A single plugin can expose multiple skills—for example, an Airtable plugin might have separate skills for reading records and creating new entries.

Can plugins include custom execution logic?

Yes, plugins can include custom execution logic by defining agents in the ./agents/ directory. These agent definitions allow the plugin to run custom code on the Codex platform beyond simple API wrappers, enabling complex workflows and stateful interactions with external services.

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