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

> Compare Codex-only plugins and general marketplace plugins. Discover how skill-based discovery and OpenAPI specifications offer distinct features for developers.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: feature-comparison
- Published: 2026-06-20

---

**Codex-only plugins rely on skill-based discovery through [`SKILL.md`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)** file that describes the plugin for the Codex runtime. This manifest contains no OAuth flow definitions or [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json) references, as authentication and execution remain internal to the Codex environment.

**Marketplace plugins** include a **[`.app.json`](https://github.com/openai/plugins/blob/main/.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:

```text
/zoom list_meetings

```

Codex resolves this command by reading [`plugins/zoom/skills/zoom-apps-sdk/SKILL.md`](https://github.com/openai/plugins/blob/main/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:

```json
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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/zoom-apps-sdk/SKILL.md))
- **[`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugins/vercel/.app.json))
- **[`README.md`](https://github.com/openai/plugins/blob/main/README.md)** — Repository root documentation confirming the curated Codex plugin collection

## Summary

- **Codex-only plugins** use [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifests and [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) files with front-matter metadata for automatic discovery within the Codex runtime.
- **General marketplace plugins** rely on [`.app.json`](https://github.com/openai/plugins/blob/main/.app.json), OpenAPI specifications, and [`.agents/plugins/marketplace.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) for Codex skill discovery and [`.app.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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.