Skills vs AGENTS.md vs MCP vs plugins vs custom prompts in Codex

The one-line version

• AGENTS.md: what Codex should know on every task in this repository.
• Skill: what Codex should know when doing one particular kind of task.
• MCP server: what Codex can reach outside the repository.
• Plugin: how you package and distribute skills and MCP servers to other people.
• Custom prompt: deprecated; use a skill.

They are not alternatives so much as layers. OpenAI’s own description is that AGENTS.md shapes behavior, skills package repeatable processes and MCP connects Codex to outside systems. Claude Code has the same layers under different names; Codex vs Claude Code maps one onto the other.

Side by side

	AGENTS.md	Skill	MCP server	Plugin	Custom prompt
What it is	Markdown instructions	Folder with SKILL.md, optional scripts and references	A process or service exposing tools	Installable bundle of skills, MCP servers, hooks, assets	Markdown file expanded as a slash command
When it loads	Start of every session	Name and description always; body when matched or mentioned	Tools listed when the server starts	Its parts load as skills and servers	Only when you type it
Context cost	Whole file, always	Small catalog entry; body on demand	Tool definitions while connected	Sum of its parts	Only when used
Triggered by	Always on	Implicit match or $name	Codex choosing a tool	Install	/prompts:name
Shared via	The repository	Repository, user folder, /etc/codex/skills, plugins	config.toml (user or trusted project)	Marketplaces, plugin directory, workspace	Not shared (~/.codex/prompts)
Runs code	No	Scripts, under your sandbox	Yes, in the server	Through its skills, servers and hooks	No
Status	Current	Current	Current	Current	Deprecated

Decision table

If you want Codex to…	Use
Always run pnpm test before finishing	AGENTS.md
Never edit src/generated/	AGENTS.md
Follow a 40-step release checklist when you cut a release	Skill
Fill PDF forms with a tested script	Skill with scripts/
Read Linear tickets or Figma frames	MCP server
Triage Sentry issues the same way every time	Skill plus the Sentry MCP server
Give ten teams the same release workflow	Plugin containing the skill
Ship a workflow that needs a connector to a SaaS tool	Plugin with the skill and the connection
Run a reusable prompt only when you type it	Skill with allow_implicit_invocation: false
Block a dangerous command at the moment it is attempted	Rules or hooks (see below)

AGENTS.md: always-on rules

Codex reads a global ~/.codex/AGENTS.md and then one file per directory from the repository root down to your working directory, concatenated so the closest file has the last word, up to 32 KiB by default. Everything in it is in context for every task. That makes it right for commands, conventions and boundaries, and wrong for anything long or occasional. The full mechanics are in the AGENTS.md guide.

Signs something should move out of AGENTS.md: it is a numbered procedure longer than ten steps, it starts with “when doing X”, or it is about a tool you use once a month.

Skills: knowledge on demand

A skill costs a line in the catalog until it is needed, then loads in full. It can carry reference files Codex reads only in edge cases, and scripts that make fragile steps deterministic. Skills live in .agents/skills (repository), ~/.agents/skills (personal), /etc/codex/skills (machine) or inside plugins. They are the right home for procedures, domain knowledge and team-specific ways of working. See what Codex skills are.

MCP: reach beyond the repository

An MCP server gives Codex tools: query a database, read a design, open a browser, create an issue. It does not teach judgment. A GitHub MCP server lets Codex open a pull request; it does not know your team wants small PRs with test evidence. That knowledge is a skill. Configuration lives in config.toml and is shared by the CLI, IDE extension and desktop app. See the Codex MCP guide.

Plugins: distribution

A plugin does not add a new kind of capability; it packages the ones above so other people can install, update and toggle them as a unit. Use one when your audience is wider than one repository or when a skill only works with a particular MCP server or connector. The IDE extension does not support plugins; the CLI and the ChatGPT desktop app do. See the Codex plugins guide.

Custom prompts: migrate to skills

Custom prompts are Markdown files in ~/.codex/prompts/ that you invoke as /prompts:name, with $1 or $ARGUMENTS placeholders. OpenAI has deprecated them in favor of skills: prompts only work when typed, and they live in your home directory where teammates cannot see them.

Migrating takes a few minutes. Given ~/.codex/prompts/draftpr.md:

---
description: Prep a branch, commit, and open a draft PR
---
Create a branch named dev/<feature_name>, commit the staged changes, open a draft PR.

Create .agents/skills/draft-pr/SKILL.md:

---
name: draft-pr
description: Creates a feature branch, commits staged changes with a clear message and opens a draft pull request. Use when the user asks to open a draft PR or ship the current work for review.
---

1. Create a branch named `dev/<feature-name>` from the current HEAD.
2. Commit only what is staged. Write a message that explains why.
3. Open a draft PR with `gh pr create --draft`, using the user's title if given.

If the old prompt should never run unless typed, add agents/openai.yaml with policy.allow_implicit_invocation: false and invoke it as $draft-pr. Positional placeholders do not carry over; write “use the title the user gave, if any” instead. The codex-custom-prompts and codex-migration-guide skills automate the conversion.

Hooks, rules and subagents

Three more mechanisms come up in the same conversations:

• Rules (experimental) are .rules files that allow, prompt or forbid specific command prefixes outside the sandbox, for example “always ask before gh pr merge”. Use them for enforcement that must not depend on the model remembering an instruction.
• Hooks run scripts or MCP tools at lifecycle points such as before a tool call or when a turn stops. Use them for logging, validation and policy checks. Non-managed hooks must be trusted before they run.
• Subagents let Codex delegate focused work to agents with their own roles and tools.

An instruction in AGENTS.md or a skill is a request; a rule or a hook is a control. If breaking it would be a security or compliance problem, use a control.

Worked examples

“Codex keeps using npm in our pnpm repo.” One line in AGENTS.md: “Install with pnpm install; never npm or yarn.” Add a lockfile check in CI for enforcement.

“Every database migration needs the same expand-and-contract review.” A skill, such as zero-downtime-migrations, committed to .agents/skills. AGENTS.md gets one pointer line.

“Codex should check the ticket before starting work.” An MCP server for the issue tracker, plus a short skill that says which fields matter and how to link the ticket in the PR.

“Our platform team wants every service to use the same deploy workflow.” A plugin containing the deploy skill and the deployment system’s MCP server, published through a team marketplace.

“I have a prompt I paste every Friday.” A personal skill in ~/.agents/skills, with implicit invocation off if it should only run on request.

Putting it together

A well-set-up repository usually ends up with a short root AGENTS.md, a handful of skills in .agents/skills for the procedures that matter, one or two MCP servers for the systems the team touches daily, and plugins for anything shared across teams. Start with AGENTS.md, add skills when instructions grow past a few lines, add MCP when Codex needs to reach outside, and package a plugin when other teams ask for a copy.