Codex Plugins Just Changed How AI Automation Ships (Skills vs MCP)

Codex plugins are not browser add-ons and they are not giant prompts. They are installable packages that can combine reusable workflow instructions, server-backed tools, lifecycle hooks, and presentation assets. That distinction matters because each component solves a different failure mode.

I traced the current plugin and skill behavior against OpenAI’s documentation as of August 27, 2026. The practical result is simple: start with a skill when Codex already has the tools it needs; create a plugin when the workflow must travel with its dependencies, permissions, and distribution metadata.

A skill tells Codex how to perform work. A plugin makes that workflow installable. MCP gives it tools Codex did not already have.

Skill

A Codex skill is a directory whose only required artifact is `SKILL.md`. The file contains a `name`, a `description`, and the workflow instructions Codex follows. The directory can also carry scripts, references, templates, assets, and interface metadata.

The non-obvious mechanic is progressive disclosure. Codex does not paste every installed skill into the working context. It starts with a compact list of names and descriptions, selects a likely match, then reads the complete `SKILL.md`. OpenAI caps the initial skill list at 2% of the model context window, or 8,000 characters when the context size is unknown. If too many skills are installed, descriptions are shortened before skills are omitted.

That makes the description routing logic, not marketing copy. A weak description such as “helps with content” forces Codex to guess. A useful description names the outcome, trigger terms, and exclusion boundary:

---
name: release-notes
description: Draft release notes from merged pull requests. Use for weekly product releases; do not use for incident reports or roadmap planning.
---

Local scope is another reason to stop at a skill. Codex scans `.agents/skills` from the current working directory up to the repository root, then considers user, administrator, and system locations. A workflow checked into one repository can appear only where it is relevant. A personal skill under `~/.agents/skills` follows the user across repositories.

Use a skill when the workflow can run with tools Codex already possesses: read files, execute approved shell commands, query an installed connector, render a document, or apply repository-specific checks. You gain reusable behavior without creating a package, marketplace entry, or service boundary. The full discovery rules are documented in OpenAI’s build-skills guide.

When a skill is not enough

A skill cannot create a remote API by describing one. It can explain how to call a CRM, but Codex still needs an authenticated tool that exposes CRM operations. It can prescribe an approval step, but the host or tool must enforce that approval. It can include a local script, but distributing that script safely across teams becomes a packaging and maintenance problem.

Those are signals to move the workflow into a plugin, add an MCP server, or do both.

Plugin

A plugin is the installable boundary around one or more capabilities. Every plugin has `.codex-plugin/plugin.json`; the manifest identifies the package and points to bundled components. A minimal plugin can contain one skill. A larger plugin can add MCP configuration, registered connections, hooks, icons, screenshots, legal links, and starter prompts.

The core directory contract is strict:

my-plugin/
├── .codex-plugin/
│   └── plugin.json
├── skills/
│   └── triage/
│       └── SKILL.md
├── hooks/
│   └── hooks.json
├── .mcp.json
├── .app.json
└── assets/

Only `plugin.json` belongs inside `.codex-plugin/`. Skills, hooks, MCP files, registered-connection mappings, and assets stay at the plugin root. This prevents the manifest directory from becoming an unstructured payload bucket.

A minimal manifest needs a stable package identity and a relative pointer to the skills directory:

{
  "name": "support-triage",
  "version": "1.0.0",
  "description": "Triage support tickets and prepare reviewed replies.",
  "skills": "./skills/"
}

The manifest does not contain the workflow itself. It acts as an index: `skills` points to instruction folders, `mcpServers` points to bundled MCP configuration, `apps` maps a registered MCP connection through `.app.json`, and `hooks` points to lifecycle behavior. The `interface` object controls how the package appears during installation, including its display name, descriptions, icons, screenshots, brand color, and default prompts.

This separation lets you version packaging without mixing it into operational instructions. It also makes review easier: a maintainer can inspect the manifest to see which components the package activates, then inspect each capability at its responsible layer. OpenAI’s plugin packaging reference defines the current layout and manifest fields.

The smallest responsible plugin

Start with one skill in one plugin. Add MCP only when the workflow needs a tool or data source unavailable in the host. Add UI only when a visual interaction materially improves the task. Add hooks only when lifecycle behavior must run at a defined event.

This sequence limits failure modes. An instruction-only plugin can fail because the instructions are ambiguous. An MCP-backed plugin adds network, authentication, schema, latency, and service-availability failures. UI adds rendering and interaction states. Hooks can execute outside the user’s immediate prompt flow. Each layer needs a reason to exist.

MCP Server

An MCP server is the capability boundary that exposes tools and structured results to the model. It can connect Codex to a remote service, a local process, or an organization’s private system. It is optional: a plugin whose workflows use existing host tools does not need MCP.

There are two integration shapes. A plugin can bundle MCP server configuration in `.mcp.json`, which is useful for a local command or a server configuration that travels with the package. It can also map a previously registered MCP server connection through `.app.json`. The second form is useful when authentication and connection management happen through the product’s developer setup.

A bundled local server can be declared as a direct server map:

{
  "docs": {
    "command": "docs-mcp",
    "args": ["--stdio"]
  }
}

After installation, users can enable or disable a bundled server and narrow its tool policy in Codex configuration. That is important: the plugin can ship a server definition, but the user or administrator retains control over whether the server runs and which tools receive automatic approval.

Do not create a generic `execute` tool that accepts arbitrary instructions. Define small operations with explicit input schemas and read/write semantics: `search_tickets`, `get_ticket`, `draft_reply`, and `send_reply` are easier to reason about than `run_support_action`. The model chooses more reliably, audit logs become legible, and destructive operations can carry appropriate confirmation friction.

MCP without custom UI

MCP can return structured data and model-readable text without rendering a widget. That is the right default for search, retrieval, data mutation, and background operations. Add a UI resource for tasks where the user benefits from inspecting, selecting, editing, or approving structured state visually. UI is an optional output surface, not proof that the server is more capable.

Permissions

Plugin permissions form three separate layers: installation, host execution, and external-service authorization. Treating them as one “connected” switch creates unsafe designs and confusing failures.

Installation makes bundled skills and tool definitions available to a new chat or CLI session. It does not silently grant access to a user’s external account.

Host execution remains governed by the Codex sandbox and approval policy. A plugin tool running through a Codex host does not escape filesystem, network, or command restrictions merely because the user installed the package.

External authorization belongs to the connected service. OAuth scopes, API roles, tenant policies, and record-level permissions decide what the connection can see or change. Signing in and approving a requested action are distinct events.

This explains a common debugging pattern: the plugin appears installed, but a tool is missing until a new session starts; the tool appears, but asks for service login; the login succeeds, but a write action still requires host approval; the host approves, but the service rejects the operation because the account lacks scope. Each failure belongs to a different layer.

For builders, the rule is least privilege. Ask only for required scopes. Mark a tool read-only only when it is side-effect-free and safe to retry. Label create, modify, and delete operations as write actions. Keep explicit confirmation for destructive actions. OpenAI’s plugin security guidance also recommends assuming that prompt-injected or malicious input will reach the server, validating every input, and retaining audit logs.

Distribution

Distribution is where a plugin earns its extra structure. Local skills are ideal during authoring. Plugins are designed to be installed, grouped, shared, and published.

A repository marketplace lives at `$REPO_ROOT/.agents/plugins/marketplace.json`; a personal marketplace lives at `~/.agents/plugins/marketplace.json`. The marketplace is a catalog that points to plugin packages and controls their install policy. It can expose one package during testing or a curated set for a team.

Codex CLI can register a marketplace source directly:

codex plugin marketplace add owner/repo --ref main
codex plugin marketplace list

Pinning a Git ref gives teams a reviewable update boundary. Sparse paths let a marketplace live inside a larger repository. Local paths work for package development before pushing anywhere.

Installation behavior depends on the surface. In Codex CLI, `/plugins` opens the browser, and a new session is required before newly installed skills and tools are loaded. Current official documentation says the IDE extension does not support plugins. Workspace-published plugins remain inside the organization; they are not automatically listed in the public directory shared by ChatGPT and Codex.

Updates need operational discipline

Version the manifest, pin marketplace sources where repeatability matters, and test installation in a clean session. Validate that descriptions still trigger the intended skill, MCP schemas match the live server, write actions request approval, and removal does not leave an unexpected external connection active. Uninstalling the package and disconnecting an external service are separate cleanup operations.

Decision Rule

Choose the smallest boundary that owns the real dependency.

• Use a repo skill for instructions specific to one codebase.
• Use a personal skill for a workflow you repeat across projects with tools already available.
• Use a skill-only plugin when other people need to install and version that workflow.
• Add an MCP server when the workflow needs authenticated tools or structured access to an external system.
• Add UI when reviewing or editing structured state visually reduces errors.
• Add hooks only for lifecycle behavior that cannot depend on the user remembering to invoke a workflow.

The mistake is starting with the biggest package. If a `SKILL.md` and existing tools can finish the job, MCP adds operational weight without adding capability. If the workflow depends on private data or external writes, instructions alone cannot supply the missing enforcement boundary.

Codex plugins matter because they separate reusable judgment from executable capability. Skills carry the procedure. MCP carries the tools. The manifest carries installation and discovery. Permissions remain enforceable at the host and service boundaries. Once those roles are clear, the architecture stops feeling new and starts feeling maintainable.