# OpenAI Plugin Marketplace Discovery: How Codex Agents Locate and Provision Plugins

> Discover how Codex agents find and use plugins in the OpenAI marketplace. Learn about the file-based convention powering plugin discovery and provisioning.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-09-10

---

**The OpenAI plugin marketplace discovery mechanism relies on a file-based convention where static JSON manifests and Markdown front-matter enable Codex agents to discover, categorize, and provision plugins without hard-coded logic or runtime hooks.**

The `openai/plugins` repository defines a lightweight discovery protocol that lets AI agents surface integrations before generating code. This system uses declarative metadata files rather than API calls to create a searchable index of capabilities. Understanding how OpenAI plugin marketplace discovery works is essential for developers building extensible AI agents or contributing new integrations.

## The File-Based Discovery Architecture

The discovery system is built around two canonical data structures: the **Plugin Manifest** that defines identity, and the **Marketplace Index** that enables resolution. Because discovery data lives in static files, agents do not need custom hooks or runtime look-ups to enumerate available capabilities.

### Plugin Manifest Declaration

Every plugin resides under `plugins/<name>/` and must contain a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file. This manifest serves as the source of truth for the plugin’s identity, declaring its capabilities, entry points, and version metadata. The Codex runtime parses this file to understand what a plugin offers without executing any of its code.

### Marketplace Index Resolution

The [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) file—by default located at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json)—maps logical plugin names to their absolute filesystem locations. When an agent needs to resolve a plugin name to its directory on disk, it reads this index. This indirection allows plugins to be relocated or symlinked without breaking discovery references.

## Skill-Level Discovery with Front-Matter Metadata

While the manifest defines plugin-level identity, granular capabilities are exposed through **Skills**. Individual actions reside in `skills/<skill>/SKILL.md` files within each plugin directory.

The YAML front-matter of a skill file contains discovery metadata such as:

- `retrieval.aliases` – Alternative names for the capability
- `intents` – User intentions this skill satisfies
- `pathPatterns` – File patterns relevant to the skill
- `bashPatterns` – Command patterns that trigger this skill

For example, the Vercel marketplace plugin uses [`plugins/vercel/skills/marketplace/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/vercel/skills/marketplace/SKILL.md) to expose integration categories. Codex parses this front-matter to perform native discovery when a user asks for capabilities like "create a storefront."

## The Categorize → Discover → Install → Build Flow

For integration-type plugins, the discovery process follows a deterministic four-step sequence that ensures safety. As implemented in the Vercel marketplace skill, this flow guarantees that code generation only occurs **after** the integration has been safely provisioned.

**Categorize** – The agent asks the user to select a broad need category (commerce, payments, messaging, etc.).

**Discover** – The agent executes a read-only CLI command to list available integrations:

```bash
vercel integration categories               # shows category slugs

vercel integration discover --category commerce  # lists top-ranked integrations

```

**Install** – The agent provisions the chosen integration:

```bash
vercel integration add shopify --yes --no-claim

```

If the integration requires a dashboard authentication step, the agent pauses and prompts the user to complete it before proceeding.

**Build** – Finally, the agent pulls environment variables and generates application code against the real integration:

```bash
vercel env pull --yes

# ...continue with app scaffolding steps

```

## Runtime Implementation and Extensibility

Because discovery relies on static files, the Codex runtime builds a searchable index by parsing [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) and skill front-matter at startup. This eliminates the need for runtime database queries or network requests during the discovery phase.

Adding a new plugin requires only two steps: creating the [`plugin.json`](https://github.com/openai/plugins/blob/main/plugin.json) manifest in the plugin directory and updating the [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) index. New capabilities become instantly discoverable to all Codex agents, preserving a plug-and-play experience.

## Practical Implementation Examples

The following Bash workflow demonstrates the complete discovery and provisioning cycle:

```bash

# 1️⃣ List all available marketplace entries (no auth needed)

$ cat ~/.agents/plugins/marketplace.json | jq '.plugins[] | {name, path}'

# 2️⃣ Categorize & discover a Vercel integration (read-only)

$ vercel integration categories               # shows category slugs

$ vercel integration discover --category commerce  # top-ranked integration

# 3️⃣ Install the chosen integration (may require user auth)

$ vercel integration add shopify --yes --no-claim

# 4️⃣ Pull env vars and start building against the real integration

$ vercel env pull --yes
$ # …continue with your app scaffolding steps

```

The following Python example shows how a Codex agent programmatically resolves a plugin name to its filesystem path using the marketplace index:

```python

# Example: A Codex agent loads the marketplace index to resolve a plugin

import json, pathlib

def resolve_plugin(name: str) -> pathlib.Path:
    market_path = pathlib.Path.home() / ".agents" / "plugins" / "marketplace.json"
    data = json.loads(market_path.read_text())
    for entry in data["plugins"]:
        if entry["name"] == name:
            return pathlib.Path(entry["path"])
    raise ValueError(f"Plugin {name!r} not found")

```

## Summary

- OpenAI plugin marketplace discovery uses a static file convention rather than runtime APIs or hard-coded logic.
- Each plugin declares its identity in a [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest stored in its root directory.
- The [`marketup.json`](https://github.com/openai/plugins/blob/main/marketup.json) index maps logical plugin names to filesystem paths, enabling the Codex runtime to locate plugins without environment-specific configuration.
- Granular capabilities are exposed through skill files ([`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md)) containing structured front-matter with aliases, intents, and patterns.
- The four-step categorize-discover-install-build flow ensures integrations are safely provisioned before any code generation occurs, preventing scaffolding errors against unconfigured services.

## Frequently Asked Questions

### Where is a plugin's canonical identity defined?

The canonical identity is declared in the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file located within each plugin's directory (`plugins/<name>/`). This manifest contains the plugin's name, version, and entry points, serving as the source of truth that the Codex runtime reads during discovery.

### How does the Codex runtime locate a plugin on disk?

The runtime consults the [`marketplace.json`](https://github.com/openai/plugins/blob/main/marketplace.json) index file, typically located at [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.agents/plugins/marketplace.json). This JSON file maps logical plugin names to their absolute filesystem paths, allowing the agent to resolve a plugin reference to its actual directory location without relying on environment variables or hard-coded paths.

### What enables discovery of specific capabilities within a plugin?

Individual capabilities are exposed as **Skills** defined in `skills/<skill>/SKILL.md` files. The YAML front-matter in these Markdown files contains metadata fields such as `retrieval.aliases`, `intents`, `pathPatterns`, and `bashPatterns` that allow Codex to match user requests against specific plugin capabilities.

### Why does the marketplace use static files instead of dynamic APIs?

The file-based approach eliminates the need for custom runtime hooks, database connections, or network requests during discovery. By parsing static files at startup, Codex agents build a searchable index of all available plugins and skills, resulting in faster resolution and ensuring that discovery works offline or in restricted environments.