What Distinguishes Codex-Only Plugins from General Marketplace Plugins: A Feature Comparison

Codex-only plugins rely on skill-based discovery through SKILL.md metadata and slash commands within the Codex CLI, while general marketplace plugins expose HTTP APIs via OpenAPI specifications with OAuth flows for broad multi-client compatibility.

The openai/plugins repository maintains two distinct plugin architectures that serve different integration patterns. While both extend AI capabilities, Codex-only plugins target the internal Codex runtime with automatic skill detection, whereas general marketplace plugins provide full API surfaces for external clients like ChatGPT. Understanding these architectural distinctions helps developers choose the correct manifest structure and deployment strategy for their specific use case.

Target Runtime and Discovery Mechanisms

Codex-only plugins are designed exclusively for the Codex AI environment (CLI/App). They utilize automatic discovery through SKILL.md front-matter metadata, specifically fields like retrieval.aliases, intents, entities, pathPatterns, and bashPatterns as implemented in plugins/zoom/skills/zoom-apps-sdk/SKILL.md.

General marketplace plugins operate across any OpenAI-compatible client. They advertise capabilities through the .agents/plugins/marketplace.json manifest, referencing OpenAPI descriptions, OAuth configurations, and optional UI elements rather than localized skill files.

Manifest Structure and Configuration

The configuration files reveal the architectural split immediately.

Codex-only plugins require a .codex-plugin/plugin.json file that describes the plugin for the Codex runtime. This manifest contains no OAuth flow definitions or .app.json references, as authentication and execution remain internal to the Codex environment.

Marketplace plugins include a .app.json file (MCP server configuration) and/or a full OpenAPI specification defining HTTP endpoints, authentication scopes, and request schemas. These files enable remote clients to generate proper REST calls against the service.

Interaction Models: Skills vs HTTP APIs

The interaction patterns diverge significantly between the two types.

Codex-only plugins expose skills located under skills/…/SKILL.md. Users invoke these through slash commands like /zoom list_meetings, where Codex matches the command against retrieval.aliases in the skill's front-matter and executes the corresponding tool without external HTTP calls.

Marketplace plugins expose commands, agents, or webhooks through HTTP endpoints defined in the OpenAPI document. Interaction occurs via REST API calls rather than slash commands, with the LLM generating POST or GET requests against the defined endpoints.

Feature Set and Installation Paths

Codex-only plugins provide a lightweight, focused feature set emphasizing:

• Automatic skill discovery and tool mapping
• Tight integration with Codex's "agent-skills" runtime
• Local installation via ~/.codex/plugins/
• No OAuth UI requirements

General marketplace plugins offer a broader capability set including:

• OAuth-protected API endpoints
• Multi-client support (ChatGPT, custom applications)
• Remote installation through the public marketplace UI
• UI components for enhanced interaction

Code Examples

Invoking a Codex-Only Plugin

In the Codex CLI environment, trigger skills using slash commands:

/zoom list_meetings

Codex resolves this command by reading plugins/zoom/skills/zoom-apps-sdk/SKILL.md. The front-matter metadata matches the "list_meetings" alias to the underlying Zoom connector tool without requiring OAuth token exchange or HTTP endpoint generation.

Calling a General Marketplace Plugin

For marketplace plugins like Vercel, clients use the OpenAPI specification to generate REST calls:

POST https://api.openai.com/v1/chat/completions
{
  "model": "gpt-4o",
  "messages": [
    {"role": "user", "content": "Deploy the Next.js app in the `my-site` folder."}
  ],
  "plugins": [
    {
      "type": "openapi",
      "url": "https://github.com/openai/plugins/blob/main/plugins/vercel/.app.json"
    }
  ]
}

The LLM interprets the OpenAPI definition from plugins/vercel/.app.json to generate a proper POST /v2/now/deployments request, handling OAuth token exchange through the marketplace manifest.

Key Source Files

• plugins/<name>/.codex-plugin/plugin.json — Required manifest for Codex-only plugins (e.g., plugins/zoom/.codex-plugin/plugin.json)
• plugins/<name>/skills/**/SKILL.md — Human-readable skill definitions with discovery metadata (e.g., plugins/zoom/skills/zoom-apps-sdk/SKILL.md)
• .agents/plugins/marketplace.json — Marketplace manifest indexing general plugins
• plugins/<name>/.app.json — MCP server and OpenAPI description for marketplace HTTP interactions (e.g., plugins/vercel/.app.json)
• README.md — Repository root documentation confirming the curated Codex plugin collection

Summary

• Codex-only plugins use .codex-plugin/plugin.json manifests and SKILL.md files with front-matter metadata for automatic discovery within the Codex runtime.
• General marketplace plugins rely on .app.json, OpenAPI specifications, and .agents/plugins/marketplace.json for multi-client HTTP API exposure.
• Codex plugins execute via slash commands and local tool mapping; marketplace plugins execute via generated REST calls with OAuth authentication.
• Installation paths differ: Codex plugins install to ~/.codex/plugins/ locally, while marketplace plugins deploy through the public marketplace UI for remote access.

Frequently Asked Questions

Can a single plugin function as both Codex-only and a marketplace plugin?

Yes. According to the openai/plugins source code, hybrid configurations exist where a repository contains both .codex-plugin/plugin.json for Codex skill discovery and .app.json with OpenAPI definitions for marketplace distribution. The plugins/vercel example demonstrates this pattern, offering slash commands for Codex users while simultaneously exposing HTTP endpoints for external clients through the marketplace manifest.

Do Codex-only plugins support OAuth authentication flows?

No. Codex-only plugins intentionally omit OAuth configurations from their .codex-plugin/plugin.json manifests. Authentication for Codex skills occurs internally within the Codex runtime environment, whereas marketplace plugins define OAuth scopes and token exchange mechanisms in their OpenAPI specifications to support third-party client authorization.

How does Codex discover skills without an OpenAPI specification?

Codex discovers skills by parsing YAML front-matter in SKILL.md files located under skills/ directories. The metadata fields retrieval.aliases, intents, entities, pathPatterns, and bashPatterns provide the discovery mechanism, allowing the Codex runtime to map slash commands like /zoom list_meetings to specific skill implementations without requiring HTTP endpoint definitions.

Where are Codex-only plugins installed on a local system?

Codex-only plugins install to the local Codex plugin library at ~/.codex/plugins/… and are discovered automatically by the Codex CLI/App runtime. This contrasts with marketplace plugins, which are accessed remotely through the marketplace JSON manifest and require no local installation to the Codex plugin directory.

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