Codex offers three ways to extend an agent: skills that carry your process, MCP servers that reach live systems, and plugins that bundle both for a team. This article shows how each one looks on disk, what it costs in context, and how to choose between them.
Open the Codex plugin browser and you will see skills, MCP servers and plugins listed side by side, as if they were three versions of the same thing. They are not. Mixing them up is how people end up writing a 400 line instruction file when they needed a ten line connector, or wiring up a server when a one page checklist would have done the job.
Here is the short version before the details. A skill teaches Codex how to do a job. An MCP server gives Codex live access to a tool or a data source. A plugin is the box that ships skills, servers and app connections together, so someone else can install them in one step. The rest of this article shows what each one looks like on disk, what it costs in context, where it breaks, and how to pick the right one for your own work.
Three objects on one workbench make the split easy to remember. The wrench is a tool you reach for. The binder tells you how to run a job. The crate is a bundle somebody packed so it can be handed to a colleague.
SKILL.md file that tells Codex when and how to run a repeatable workflow.None of them replaces the others. A plugin is not a fourth kind of capability. It is packaging for the first two, plus app connections, with a version number attached.
A skill is a recipe card: ordered steps, quantities and a description of what "done" looks like. An MCP server is an appliance wired into the wall: it does things the cook cannot do by hand, like blending or refrigerating. A plugin is the meal kit: the card, the ingredients and a note about which appliance you need, all in one box.
💡 Rule of thumb: if the problem is "Codex does not know our process," write a skill. If it is "Codex cannot reach that system," add an MCP server. If it is "teammates keep asking how I set this up," build a plugin.
The Model Context Protocol is an open standard, introduced by Anthropic in late 2024, that lets an AI client talk to outside tools through one common interface. Codex plays the client. The server is whatever you point it at: a GitHub connector, a database bridge, a documentation search, an image generator.
An MCP server answers one question: what can you do right now, and with what data? It lists tools with names, descriptions and input schemas. When Codex decides a tool fits the task, it calls the tool and reads the result. Nothing in the server says how your team prefers to use it. A database server will run any query you permit, but it will not tell Codex that nobody touches the billing tables on a Friday afternoon.
That gap is why servers and skills pair so well. The server supplies the reach. The skill supplies the judgment.
Codex stores MCP settings in ~/.codex/config.toml, with project scoped settings possible in .codex/config.toml. A local server that Codex starts itself (STDIO) looks like this:
[mcp_servers.docs]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
A remote server over streamable HTTP uses a URL instead:
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
You can also run codex mcp add <name> -- <command> to write the entry for you, codex mcp list to see what is configured, and codex mcp login <server-name> to run OAuth for servers that need it.
A few settings deserve attention. startup_timeout_sec defaults to 10 seconds, which can be tight for a slow first npx download. tool_timeout_sec defaults to 60 seconds, which will cut off long jobs such as a video render. enabled_tools and disabled_tools let you trim a server down to the calls you actually want the agent to see.
The costs of MCP are real. Every connected server adds tool definitions the model has to carry, a process or a network hop that can fail, and a new trust boundary. A server that can write to your repository can also write something you did not intend.
A skill is a folder. Inside is a SKILL.md file that opens with a short YAML header, set between two fence lines at the top of the file. The header holds a name and a description:
name: release-notes
description: Use when the user asks for release notes or a changelog built from merged pull requests. Do not use for commit message drafts.
Below the header, the instructions are plain markdown:
1. List the pull requests merged since the last tag.
2. Group them under Added, Changed and Fixed.
3. Write one plain sentence per item.
4. Save the result to docs/releases/<version>.md.
The folder can also hold scripts, reference documents, templates and assets that the instructions point to. Codex looks for skills in .agents/skills inside the repository (the working directory, its parents and the repo root), in $HOME/.agents/skills for personal skills, in /etc/codex/skills for shared machine wide ones, and in the built-in set that ships with Codex.
Skills use progressive disclosure. At the start of a session Codex sees only the list of skill names and descriptions, and that list is capped at about 2% of the context window (or 8,000 characters when the window size is unknown). The full SKILL.md loads only after a skill is selected. It works like a card catalog: you read the cards until you find the right drawer, then you pull the whole file.
The consequence is practical. You can keep dozens of skills installed without paying for all of them on every request. It also means the description line does the heavy lifting. A vague description such as "helps with docs" never triggers. A precise one that says when to use the skill and when to leave it alone triggers reliably.
There are two ways to run a skill. Explicit: type $release-notes in the Codex CLI or the IDE extension (ChatGPT uses @release-notes). Implicit: Codex picks the skill on its own when your request matches the description. An optional agents/openai.yaml file adjusts how the skill appears in the interface, its invocation policy and the tools it depends on.
💡 If a skill never fires on its own, rewrite the description before you rewrite the instructions. The description is the trigger.
Plugin support reached Codex in March 2026, and the launch set of more than 20 plugins included Box, Figma, Linear, Notion, Sentry, Slack, Gmail and Hugging Face. The reason plugins exist is distribution. A skill can be copied into a folder and a server can be pasted into a config file, but handing both to ten teammates with matching versions is tedious and easy to get wrong.
my-plugin/
plugin.json
mcp.json
skills/
release-notes/
SKILL.md
hooks/
assets/
scripts/
plugin.json at the root is the manifest, and .codex-plugin/plugin.json still works as a fallback. It holds the name in kebab case, a version, a description and author details. Skills sit in skills/<skill-name>/SKILL.md and are picked up from that folder without being declared. MCP servers go in mcp.json under mcpServers, with "type": "streamable-http" for remote endpoints. Hooks run commands at set points in the lifecycle.
To test locally, add an entry whose source.path points at your folder to a marketplace file at ~/.agents/plugins/marketplace.json or $REPO_ROOT/.agents/plugins/marketplace.json, then install it from the plugin directory. The @plugin-creator helper can scaffold the folder and the marketplace entry for you.
In the Codex CLI, run /plugins to open the plugin browser and install from the marketplaces you have configured. In the ChatGPT desktop app or on the web, open the Plugins tab, search, press the plus button and connect any outside service when prompted. After that you can ask in plain language ("Summarize unread Gmail threads from today") or type @ followed by the plugin name to call it explicitly.
A plugin also adds a manifest, a version to maintain and a marketplace entry. If you are the only person who uses the workflow, a skill in $HOME/.agents/skills and one block in config.toml do the same job with less ceremony.
💡 Codex documentation moves fast. File names and commands above follow OpenAI's pages for plugins, MCP and skills as of October 2026. Check them before you build.
| Skill | MCP server | Plugin | |
|---|---|---|---|
| What it is | Folder with SKILL.md | Running tool or data service | Installable package |
| Gives Codex | A procedure | Live reach and actions | Both, plus app connections |
| Lives in | .agents/skills | config.toml | plugin.json and mcp.json |
| Loads | Name and description first, body on demand | Tool definitions at connect time | Whatever it bundles |
| Needs code | No | Yes, or a hosted server | Only if it bundles a server |
| Best for | Repeatable team process | Systems Codex cannot reach | Sharing a whole setup |
| Main risk | Vague description never triggers | Over broad permissions | Version drift, hidden bundled servers |
Skills are the cheapest of the three because only a short description sits in context until the skill is needed. An MCP server is heavier: its tool list is carried into the session whether or not the task uses it, so ten chatty servers can crowd out the actual work. A plugin inherits the cost of everything inside it.
One habit saves a lot of tokens. Before you add a server, ask whether a skill with a short script could do the same thing. Scripts inside a skill run only when the skill runs. A server stays connected the whole time.
A skill is text plus optional scripts, so its danger lives in whatever commands the instructions tell Codex to run. A server is a live process with its own credentials, which makes permissions the main concern. Trim it with enabled_tools and disabled_tools, and use default_tools_approval_mode to decide how much Codex may do without asking.
A plugin can bundle servers, skills and hooks all at once, so open the plugin.json, the mcp.json and the hooks folder before installing one from a stranger. Keep tokens in environment variables, the way bearer_token_env_var expects, and never in a file you commit.
AGENTS.md file is enough.When you are unsure, work upward from the smallest option. Start with a prompt. If you repeat it three times, turn it into a skill. If the skill needs a system Codex cannot reach, add a server. If other people need the same pair, wrap it in a plugin.
Putting process inside a server. Tool descriptions are for explaining what a tool does, not how your team works. Long policy text in a server bloats every session. Move it to a skill.
Rebuilding a connector with shell scripts. If a maintained MCP server already exists for the system you want, a skill full of curl commands will be slower to write and harder to keep working.
Packaging too early. A plugin with one author and one user is overhead. Wait until a second person asks for your setup.
Picture a small marketing team that needs consistent blog photos. The three pieces split cleanly. The skill, call it brand-photos, holds the rules: 16:9 for article images, natural light, no text inside the picture, a filename pattern and who approves the final set. The MCP server does the actual generation. The plugin ships both to every teammate so nobody edits a config file by hand.
PicassoIA offers a developer API at api.picassoia.com/v1 and an MCP connector for its image and video models, including PicassoIA Image and PicassoIA Image Editor Pro. That makes the server half of this pattern available today. Connection details live in your account, so confirm that your client supports the connector before you wire it in.
The skill then tells Codex how to use that reach well: which prompt structure to follow, which ratio to request, and when to stop and ask a human. The server never needs to know any of it.
You do not have to write the first SKILL.md by hand. A coding model such as GPT 5.6 Sol or Claude Sonnet 5 can produce a draft in seconds.
.agents/skills/brand-photos/SKILL.md.$brand-photos and a real request. If Codex does not pick it up on its own, tighten the description and try again.💡 Treat model output as a first draft. A skill is only as good as the checks you add after you watch it run on a real task.
Skills, servers and plugins are easier to judge once you watch them produce something. Open Picasso IA and recreate the photos in this article: a developer's oak desk at golden hour, a canvas tool roll beside a stack of index cards, a kraft box packed for shipping. Start with PicassoIA Image, change one detail per run, such as the lens, the light direction or the surface texture, and see how the picture shifts.
Then ask what the second run needed that the first did not. Was it a rule you keep repeating? That is a skill waiting to be written. Was it a system you had to open by hand? That is a server. Was it a setup you want to give to a friend? That is a plugin. Try a few prompts on Picasso IA today and let your own workflow tell you which one you need.
