Codex plugins: what they are and when to package one

What a plugin is

In Codex, skills are the authoring format and plugins are the distribution format. A plugin is an installable package that can contain:

• Skills: one or more skill folders, the same SKILL.md format you write locally.
• MCP servers: connections that give Codex tools for systems like GitHub, Slack or Google Drive, optionally with custom UI in ChatGPT.
• Browser extensions a workflow depends on.
• Hooks: commands that run at lifecycle points in the Codex runtime. Hooks from plugins must be reviewed and trusted before they run.
• Assets: icons and presentation material.

ChatGPT and Codex use one universal plugin directory, so a public plugin is discoverable from both. OpenAI’s examples include a Codex Security plugin for scanning authorized code, and plugins for Gmail, Google Drive and Slack.

Where plugins work

Surface	Plugins
Codex CLI	Yes: /plugins browser and codex plugin commands
Codex in the ChatGPT desktop app	Yes: Plugins tab
ChatGPT on the web, desktop and mobile (Chat and Work)	Yes
Codex IDE extension	No

Some plugins are marked Desktop only and need the ChatGPT desktop app. If you sign in to Codex with an API key, you can install supported OpenAI-curated plugins in the CLI and desktop app, but plugins whose connection flow needs unsupported OAuth capabilities are not available.

Install and manage plugins in the CLI

Inside a session:

/plugins

The browser groups plugins by marketplace. Switch tabs to change source, open a plugin to see what it contains, install or uninstall it, and press Space on an installed plugin to turn it on or off. Bundled skills and tools become available in the next session, so start a new one after installing.

From a shell:

codex plugin list --json
codex plugin add my-plugin@team-tools
codex plugin remove my-plugin@team-tools

Marketplaces are the sources plugins come from. Add one from GitHub, another Git host or a local directory:

codex plugin marketplace add your-org/codex-plugins
codex plugin marketplace add your-org/codex-plugins --ref main
codex plugin marketplace add ./local-marketplace
codex plugin marketplace list
codex plugin marketplace upgrade
codex plugin marketplace remove team-tools

If a plugin includes MCP servers, it may ask you to connect or authenticate during install or on first use. Uninstalling removes the bundle; separately connected services stay connected until you disconnect them.

How plugins relate to skills, MCP and connectors

Skills inside a plugin behave like any other skill: Codex sees their names and descriptions, loads the body on demand, and you can mention them with $. Plugin skills are namespaced by the plugin, which avoids name clashes with your own folders.

MCP servers inside a plugin start from the plugin, so you do not write a command for them. You can still restrict them in config.toml:

[plugins."sample@test".mcp_servers.sample]
enabled_tools = ["read", "search"]
default_tools_approval_mode = "prompt"

Connectors (called apps in the CLI) are integrations with external services. In the CLI, /apps lists them and inserts one into your prompt as $app-slug. A plugin can bundle a registered connection so the skill and the service it uses install together; OpenAI’s guidance is to package a plugin when you want to ship a skill alongside a connector.

When a plugin’s capability runs through Codex on your machine, your sandbox and approval policy still apply. External services use their own authentication and permissions.

Plugin or plain skill folder?

Situation	Use
A skill for one repository	.agents/skills/<name>/ committed to the repo
A skill for yourself across repositories	~/.agents/skills/<name>/
Several related skills that should install and update together	Plugin
A skill that needs an MCP server or connector to work	Plugin
Distributing to people outside your repository or team	Plugin in a marketplace
Rolling out to everyone in a ChatGPT workspace	Plugin, published to the workspace by an admin

Plain folders are faster to iterate on: edit SKILL.md and Codex picks up the change. Start there, and package a plugin once the skill is stable and you know who needs it.

Anatomy of a plugin

A portable plugin has a plugin.json manifest at its root, using the Agent Plugins schema, plus optional folders:

release-tools/
├── plugin.json
├── skills/
│   ├── release-notes/
│   │   └── SKILL.md
│   └── version-bump/
│       └── SKILL.md
├── mcp.json          # optional: bundled MCP servers
└── assets/

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "release-tools",
  "version": "1.0.0",
  "description": "Release notes and version bumps for our services"
}

Use a stable kebab-case name; hosts use it as the plugin identifier and namespace. Portable packages discover skills from the root skills/ directory automatically. OpenAI-specific settings go under extensions.com.openai in plugin.json, and the older .codex-plugin/plugin.json layout is still supported as a compatibility fallback.

The fastest way to scaffold one is the built-in creator:

$plugin-creator create a plugin called release-tools from the skills in .agents/skills/release-notes and .agents/skills/version-bump, with a personal marketplace entry for testing

It currently generates the .codex-plugin/plugin.json compatibility layout and can add a local marketplace entry so you can test the plugin straight away.

Share plugins through a marketplace

A marketplace is a JSON catalog of plugins. Put a repository-scoped one at .agents/plugins/marketplace.json or a personal one at ~/.agents/plugins/marketplace.json:

{
  "name": "team-tools",
  "interface": { "displayName": "Team tools" },
  "plugins": [
    {
      "name": "release-tools",
      "source": { "source": "local", "path": "./plugins/release-tools" },
      "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
      "category": "Productivity"
    }
  ]
}

source.path is relative to the marketplace root and must start with ./. Entries can also point at Git repositories or npm packages. Each entry needs policy.installation, policy.authentication and category.

To switch a marketplace plugin on or off for one project, use the project’s .codex/config.toml (loaded only for trusted projects):

[plugins."release-tools@team-tools"]
enabled = true

Workspace admins can also publish a plugin to their ChatGPT workspace for selected roles, which keeps it inside the organization rather than the public directory. Public listing goes through OpenAI’s submission process.

Before installing a third-party plugin

A plugin can carry more than instructions: MCP servers that act on external systems and hooks that run commands. Read what it contains before installing, prefer plugins from publishers you can identify, and keep approval prompts on for tools that write. The skill safety guide covers the review process, and the codex-plugin-packaging skill helps Codex package your own skills correctly.