Codex Plugins: How to Install, Build, and Use OpenAI's New Plugin System

OpenAI’s plugin story for Codex stopped being experimental this week.

The first building block arrived on March 5, 2026, when Codex CLI 0.110.0 added a plugin system that could load skills, MCP entries, and app connectors from config or a local marketplace. On March 25, OpenAI published the full plugins documentation, exposed curated plugins in the Codex directory, and documented how to build repo-scoped and user-scoped plugin marketplaces. On March 26, CLI 0.117.0 pushed the feature another step forward by making plugins a first-class workflow in /plugins, including install, removal, sync, and clearer setup handling.

That sequence matters because it shows what Codex plugins are meant to be. OpenAI is positioning them as a packaging layer for repeatable workflows that need instructions, integrations, and distribution.

What Codex plugins actually are

OpenAI defines plugins as installable bundles for reusable Codex workflows. A plugin can package three things in one unit:

Skills
App integrations
MCP server configuration

That packaging model is the important part. Skills are still the authoring format. They are where the instructions live. Plugins are the distribution format. OpenAI says that directly in its current Codex help documentation: skills remain the authoring format for reusable workflows, while plugins are the installable unit developers can move across projects or teams.

That distinction solves a real problem for teams using Codex in more than one place. A personal skill folder works fine when one person is iterating in one repo. It breaks down when a team wants the same setup available in the app, CLI, IDE extension, and enterprise workspace without hand-copying files.

Where you can use Codex plugins

Plugins now show up across the main Codex surfaces:

Codex app
Codex CLI
Codex IDE extensions

In the app, curated plugins appear in the Codex directory. In the CLI, the plugin surface lives behind the /plugins command. For local development, OpenAI recommends using the built-in @plugin-creator skill to scaffold a plugin and add a marketplace entry for testing.

This rollout is also broader than a local desktop feature. OpenAI’s help center says plugin access in Business and Enterprise/Edu workspaces follows workspace app controls, and that the same controls apply across ChatGPT web, Atlas, ChatGPT mobile, and Codex. In practice, that means plugins are being treated as part of OpenAI’s wider product surface, not as a niche Codex-only experiment.

How installation works

Codex supports three marketplace sources today:

The curated marketplace that powers the official Plugin Directory
A repo marketplace at $REPO_ROOT/.agents/plugins/marketplace.json
A personal marketplace at ~/.agents/plugins/marketplace.json

The repo marketplace is the more interesting one for teams because it gives a project its own install catalog. You can keep plugins under ./plugins/, point a marketplace entry at them with a ./-prefixed relative path, and make that plugin available to everyone working in the repository.

OpenAI’s documented repo layout looks like this:

{
  "name": "local-repo",
  "plugins": [
    {
      "name": "my-plugin",
      "source": {
        "source": "local",
        "path": "./plugins/my-plugin"
      },
      "policy": {
        "installation": "AVAILABLE",
        "authentication": "ON_INSTALL"
      },
      "category": "Productivity"
    }
  ]
}

The mechanics are straightforward:

Put the plugin folder somewhere your marketplace can reference.
Add the plugin entry to the marketplace JSON.
Restart Codex so it picks up the catalog.

Codex then installs plugins into a cache under ~/.codex/plugins/cache/$MARKETPLACE_NAME/$PLUGIN_NAME/$VERSION/. For local plugins, the version is recorded as local.

This is a practical design. It keeps the source plugin separate from the installed copy, which is what you want when teammates are iterating on shared tooling.

What goes inside a plugin

Every Codex plugin has one required file:

.codex-plugin/plugin.json

Everything else is optional, but OpenAI’s structure is already opinionated enough to be useful:

my-plugin/
  .codex-plugin/
    plugin.json
  skills/
  .app.json
  .mcp.json
  assets/

The required manifest can stay minimal if you are packaging one skill:

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable greeting workflow",
  "skills": "./skills/"
}

Published plugins can carry much richer metadata. OpenAI’s example manifest includes:

author
homepage
repository
license
keywords
skills
mcpServers
apps
interface

The interface object is where the install surface gets its presentation details. That includes display name, category, descriptions, brand color, starter prompts, screenshots, and legal links.

That is a meaningful design choice. OpenAI is not treating plugins as hidden config. It is treating them as installable products with identity, metadata, and presentation rules.

When a plugin makes more sense than a skill

OpenAI’s guidance here is sensible.

Use local skills when the workflow is personal, project-specific, or still changing quickly. Package it as a plugin when you want versioning, repeatable installation, or a stable bundle that combines skills with connectors and MCP config.

That creates a clean progression:

Start with a skill.
Prove the workflow is useful.
Package it as a plugin when more people need it.

For teams, this matters because the packaging unit is finally aligned with how agent setups are actually shared. Many real Codex workflows need more than instructions. They need app access, MCP endpoints, default prompts, and install rules. A plugin gives you one place to define all of that.

Why this is important for Codex

OpenAI’s March 4 Codex app launch already pointed in this direction. The app pitch was about managing multiple agents, built-in worktrees, automations, and a library of reusable skills. Plugins add the missing packaging layer that lets those workflows travel.

That changes Codex in three ways.

First, it makes Codex easier to standardize inside a company. A team can ship an approved plugin instead of sending around setup docs.

Second, it makes integrations more durable. If a workflow depends on a skill, a connector mapping, and an MCP server, those pieces no longer have to drift apart.

Third, it gives OpenAI a clearer distribution model. The official Plugin Directory can feature curated installs now, and the docs already say self-serve public publishing is coming soon.

That last point is worth watching. OpenAI has not opened public plugin publishing yet. The current documentation says both “Adding plugins to the official Plugin Directory is coming soon” and “Self-serve plugin publishing and management are coming soon.” So the system is real, but the public marketplace is still in an early phase.

The near-term limit

The biggest limitation today is distribution, not structure.

The file format is documented. Repo and personal marketplaces are documented. The plugin surface in the app and CLI is documented. The missing piece is a mature public publishing flow with ranking, discovery, version management, reviews, and lifecycle tooling.

That means early adopters should think of Codex plugins as a strong internal packaging system first, and an external marketplace opportunity second.

Even with that limitation, the direction is clear. OpenAI now has:

A skills catalog
A plugin manifest
Repo and user marketplaces
Curated plugin distribution in product
Enterprise policy controls

That is enough to make plugins one of the more consequential Codex additions of the month.

If you use Codex alone, the built-in skills catalog may still be enough. If you run Codex across a team, plugins are where the product starts to feel operational instead of personal.