Guides to Codex skills
Short, practical reading for people who use Codex every day: how skills load, where they live, how to write one that triggers when it should, and how to share them without surprises.
Start here
What a skill is, how to install one and which to pick first.
- Start here What are Codex skills? How they load, where they live and how to use them Codex skills are folders of instructions Codex loads only when a task needs them. How loading works, where skills live, how to invoke them, where to get them.
- Start here How to install skills in Codex: every method, step by step Install Codex skills with one command, an interactive picker, a manual copy, git and symlinks, or $skill-installer. Then verify, update and remove them.
- Picks The best Codex skills, picked by role An opinionated list of Codex skills worth installing, grouped by role: everyday engineering, Codex setup, frontend, backend, testing, security and AI.
How the pieces fit
SKILL.md, AGENTS.md, MCP, plugins and the open standard behind them.
- Reference AGENTS.md for Codex: discovery, precedence, size limits and examples What an AGENTS.md file is, how Codex finds, merges and caps it, what to put in one, override files, examples for three repos, and when a skill fits better.
- Reference SKILL.md format reference for Codex The SKILL.md file format for Codex skills (not skills.md): frontmatter fields, naming rules, triggering descriptions, body structure, scripts, openai.yaml.
- Reference Codex MCP: add, configure and debug MCP servers Connect MCP servers to Codex with codex mcp add or config.toml, control tools and approvals, fix servers that fail to start, and choose MCP or a skill.
- Reference Codex plugins: what they are and when to package one What Codex plugins contain, how they relate to skills, MCP servers and connectors, how to install them in the CLI, and when a plugin beats a skill folder.
- Reference Agent Skills: the open format, which tools read it, and portable skills Agent Skills is an open format for instructions agents load on demand: the spec, which tools read it, where each looks, and how to keep skills portable.
- Comparison Skills vs AGENTS.md vs MCP vs plugins vs custom prompts in Codex When to use AGENTS.md, a skill, an MCP server, a plugin or a custom prompt in Codex, with a decision table, worked examples and a custom prompt migration.
- Reference Codex CLI guide: install, commands, config, sandbox, skills and MCP How to install Codex CLI on macOS, Linux and Windows, sign in, and use it: commands, codex exec for CI, config.toml, sandbox modes, AGENTS.md, skills and MCP.
- Comparison Codex vs Claude Code: instructions, skills, MCP, permissions and headless runs compared Codex vs Claude Code on what you set up and use daily: instruction files, skills, MCP, permissions, headless runs and plugins, plus one skill set for both.
Write your own
A first skill end to end, worked examples, and fixing one that never loads.
- Tutorial Write your first Codex skill: $skill-creator and by hand Build a real Codex skill with $skill-creator and by hand, add a helper script, and test that it triggers when it should and stays quiet when it should not.
- Troubleshooting Codex skill not triggering? How to diagnose and fix it Why a Codex skill does not load and how to fix it: wrong path, broken frontmatter, disabled skills, weak descriptions, a crowded catalog, and $ mentions.
- Examples Codex skill examples: eight patterns from real skills, annotated Eight annotated Codex skill examples from working skills: definitions of done, decision tables, conditional references, bundled scripts and output contracts.
Share and stay safe
Rolling skills out to a team and checking what you install.
- Teams Share Codex skills with your team: repo skills, review, versioning and plugins How teams share Codex skills: commit them to .agents/skills, review and validate them in CI, version them, use /etc/codex/skills, and package plugins.
- Security Are Codex skills safe? What a skill can do and how to review one What a Codex skill can actually do, how the sandbox and approvals contain its scripts, the real risks of third-party skills, and a review checklist.