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

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 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 file—by default located at .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 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:

vercel integration categories               # shows category slugs

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

Install – The agent provisions the chosen integration:

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:

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 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 manifest in the plugin directory and updating the 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:

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

# 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 manifest stored in its root directory.
• The 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) 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 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 index file, typically located at .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.

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