OpenAI shipped Codex plugins: your agent config surface just moved out of the repo

#ai #openai #devtools #mcp

Plugins for Codex went live this week, with more than 20 already listed, Gmail and Figma among them, and a browsable Plugin Directory promised next (NewsBytes, Oct 4). I spent the morning reading the plugin docs and the packaging spec instead of the launch tweets, because the marketing copy hides the part that matters to anyone who maintains agent configs. A plugin is not a menu entry. It is a folder that drops skills, connectors, and MCP servers into your agent's context. That is a config surface, and it now lives partly outside your repository.

What actually landed

From the official docs, the shape of the release:

Plugins bundle skills, connectors, or both. Installed plugins "add skills, connectors, and MCP tools to new chats."
They work in ChatGPT Work on the web and in the ChatGPT desktop app under Work or Codex. The Codex CLI gets a plugin browser for Codex environments. Plain Chat, the IDE extension, and mobile are excluded for now.
Distribution is a universal directory shared by ChatGPT and Codex, with published plugins "listed once" for both surfaces. A submission portal handles review before listing.
Alongside the public directory there are private channels: a repo-scoped marketplace at $REPO_ROOT/.agents/plugins/marketplace.json and a personal one at ~/.agents/plugins/marketplace.json.

The GitHub examples repo (openai/plugins) shows the layout every plugin follows.

What a plugin is on disk

The portable package format is small enough to hold in your head:

my-plugin/
  plugin.json      # identity, version, description
  skills/          # SKILL.md folders, loaded into context
  mcp.json         # bundled MCP servers, with transport types
  assets/          # icons, screenshots
  .codex-plugin/   # optional legacy compatibility manifest

Two details stand out when you have written rules files for a while. First, skills/ and mcp.json are canonical: a skills or mcpServers declaration in a manifest "can't replace, disable, or add to those components." The folder is the source of truth, not the manifest describing it. Second, OpenAI-specific behavior lives in extensions.com.openai inside the root plugin.json, and when that object is present it replaces the entire .codex-plugin/plugin.json overlay rather than merging with it. Two files, last-write-wins, no union. Anyone who has debugged a conflicted .cursorrules knows this genre of surprise.

There is also a scaffolding path: an @plugin-creator skill generates the compatibility manifest and a local marketplace entry. Convenient for authors, and one more reason a machine can end up with plugins installed that no human on the team explicitly reviewed.

The marketplace files decide what loads

This is the detail I would flag in any team review. Which plugins are offerable to your agent is controlled by JSON files inside the repo and the home directory:

{
  "plugins": [
    {
      "source": { "path": "./tools/doc-search" },
      "interface": { "displayName": "Doc Search" }
    }
  ]
}

A repo marketplace pins your team's approved set, which is good. But a personal marketplace in ~/.agents/plugins/marketplace.json sits outside code review entirely, exactly like a global CLAUDE.md or a ~/.codex/AGENTS.md. The docs are explicit that marketplaces "control plugin ordering and install policies." If your threat model stopped at dotfiles in the repo, it now has a second front.

Where AGENTS.md still rules

None of this replaces instruction files. The AGENTS.md guide still has Codex building its instruction chain at session start: global file under ~/.codex first, then a walk from the project root down to your working directory, at most one file per directory, concatenated root-down, with a 32 KiB cap (project_doc_max_bytes) on the combined prompt. Plugins add capabilities and tools. AGENTS.md still shapes behavior. Those are different layers, and conflating them is how teams end up with rules that describe tools they no longer have installed.

I wrote about this split when Anthropic settled the same question on the MCP side (skills over MCP is final): the industry keeps converging on folders-of-instructions plus tool manifests as the unit of extension.

The audit gap nobody is talking about

Put the pieces together. An installed plugin can add MCP servers, which means network endpoints your agent will call. It can add skills, which are instructions your agent will read, with the same standing as prose you wrote yourself. And the list of what is installed can come from three places: a public directory you do not control, a repo file your team reviews, and a personal file nobody reviews.

So the question that mattered for rules that agents ignore now has a harder twin: what instructions is your agent reading that you never wrote? When a plugin's skill contradicts your AGENTS.md, the precedence rules get murky fast, because a skill arrives bundled with tools that make its instructions locally sensible. "Always use the doc-search tool before answering" is harmless prose until the tool is gone.

How I pin this down

I keep agent config versioned and diffable, the approach I described in managing config across repos, and plugins change that checklist rather than replace it:

Commit the repo marketplace file and treat plugin additions as code review items, not installs.
Audit ~/.agents/plugins/marketplace.json on every machine that runs an agent, same as you audit global instruction files today.
Record plugin names and versions next to your rules file, so a config reproduction includes the extension surface, not just the prose.
Before adopting any plugin, read its skills/ folder end to end. It is short. That is the whole point of the format.

If you want a ready-made starting point for the versioned part, my AgentConfig Studio kit ($29) ships pinned, audited config for Claude Code, Cursor, and Codex-style agents, and the free Next.js sample shows the layout for one real repo.

Worth watching

The Plugin Directory does not have a firm date yet, and the docs note that local and repo marketplace availability "can vary by surface." The exclusion list (no plugins in Chat, the IDE extension, or mobile) tells you where OpenAI thinks the risk sits: the surfaces where an agent actually executes code get plugins first, and also get the scrutiny. That is the right instinct, and it is why your audit trail should grow at the same pace as the directory.

DEV Community