Codex plugins vs skills.
A skill teaches Codex how to do one kind of work. A plugin is the package you install, and it can hold several skills plus the tools they need. Here is how they fit together and which one to reach for.
Updated November 1, 2026 · 6 min read
The short answer
| Skill | Plugin | |
|---|---|---|
| What it is | A folder of instructions, with optional scripts and reference files | An installable bundle of capabilities |
| Contains | A SKILL.md file, plus optional scripts and assets | Skills, MCP servers, browser extensions, and hooks |
| Adds new tools? | No. It guides Codex through tools it already has | Yes, through bundled MCP servers |
| How you get it | Copy the folder, or use $skill-installer | Install from the plugin directory or a marketplace |
| Best for | Your own workflows, in one repository or on your machine | Sharing a complete workflow with other people |
What is a Codex skill?
A skill is a directory with a SKILL.md file. The file starts with a name and a description, followed by instructions written in plain Markdown. The folder can also hold scripts/, references/, and assets/.
---
name: brand-ui-review
description: Review UI mockups against our brand guidelines. Use when the user asks for a design review.
---
Check every screen for:
- Colors from the brand palette only
- Inter for UI text, 16px minimum for body copy
- 8px spacing grid
Codex reads only the name and description of each skill at first. When a task matches a description, or when you mention the skill by name, it loads the full instructions. That keeps many skills available without filling the context window.
Where skills live
- In a repository:
.agents/skills. Codex checks every directory from where you are working up to the repository root. - For your user:
~/.agents/skills - For an organization:
/etc/codex/skills, managed by an admin. - Built in: system skills that ship with Codex.
How to use one
In the Codex CLI or IDE extension, run /skills or type $ to mention a skill directly. Codex can also choose a skill on its own when your request matches its description. To create a skill, ask the built-in $skill-creator. To install one from a catalog or repository, use $skill-installer. Restart Codex if a new skill does not appear.
What is a Codex plugin?
A plugin packages capabilities so they can be installed in one step. According to OpenAI’s documentation, a plugin can include:
- Skills, the reusable instructions described above.
- MCP servers, which give Codex new tools, such as access to GitHub, Slack, or a local app.
- Browser extensions for workflows that need browser capabilities.
- Hooks, commands that run at set points in the Codex runtime. Review them before you trust them.
You install plugins from the Plugins Directory, which ChatGPT and Codex share, or from a marketplace such as a Git repository. In the Codex CLI, run /plugins to browse. Plugins work in the Codex CLI and in Codex inside the ChatGPT desktop app; the IDE extension does not support them. Start a new session after installing so the new skills and tools load.
An example: how Codex Design is built
Codex Design is a plugin, and it needs both parts:
- An MCP server adds the canvas tools: create a canvas, open it, and add or move image and HTML nodes. Without these, Codex has no canvas to work on.
- A skill explains how to use those tools well: open the canvas before adding screens, keep each HTML file self-contained, and size each screen to its device.
A skill alone could describe a canvas, but it could not create one. An MCP server alone would offer the tools without the know-how. The plugin delivers both with one install command. See how to install Codex Design.
Which one should you use?
Write a skill when…
- The workflow only needs tools Codex already has, such as reading files and running commands.
- It is specific to one project, like your team’s design review checklist.
- You want to iterate quickly: editing a Markdown file is all it takes.
Build or install a plugin when…
- Codex needs new tools or access to another service.
- You want to bundle several skills that belong together.
- Other people should be able to install the whole workflow at once.
Frequently asked questions
Can a plugin contain more than one skill?
Yes. A plugin can bundle several skills, alongside MCP servers and other parts.
Are Codex skills the same as Agent Skills?
Codex skills build on the open Agent Skills format. A skill written for another agent that uses the same SKILL.md format can usually be copied into .agents/skills and used in Codex.
How do I turn off a skill without deleting it?
Add a [[skills.config]] entry with the skill’s path and enabled = false to ~/.codex/config.toml, then restart Codex.