# What Is the OpenAI Plugins Repository? A Complete Guide to Codex Extensions > Explore the OpenAI plugins repository, a guide to Codex extensions that showcases how to enhance Codex capabilities with standardized manifests and skill definitions. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: tutorial - Published: 2026-06-24 --- **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//` and contains specific metadata files that define its capabilities and entry points. ### The Plugin Manifest Every plugin must contain a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/README.md), the manifest specifies the plugin name, version, capabilities, and paths to skills and optional app configurations. ```json { "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`](https://github.com/openai/plugins/blob/main/.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: ```json { "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`](https://github.com/openai/plugins/blob/main/SKILL.md) file that describes the skill's behavior, input parameters, and output format. Plugins may also include: - [`./.app.json`](https://github.com/openai/plugins/blob/main/./.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) in your plugin directory: ```json { "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`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json): ```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`](https://github.com/openai/plugins/blob/main/skills/my-skill/SKILL.md) to define the behavior: ```markdown # 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: ```python # 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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) that defines metadata and capabilities - **The marketplace file** at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json) controls plugin discovery and installation policies - **Skills are documented** in [`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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//` 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`](https://github.com/openai/plugins/blob/main/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.