TL;DR
A Codex skill is a folder with a SKILL.md file (plus optional scripts and references) that Codex loads on demand to run a repeatable workflow. Codex sees only each skill’s name, description, and path until it decides one matches your task, then it reads the full SKILL.md. You can browse skills with /skills, force one with $skill-name, or let Codex pick implicitly from your wording. This guide covers where skills live, what a good SKILL.md looks like, and when a skill beats an AGENTS.md rule, an MCP server, or a plugin.
Version note: Agent Skills shipped for Codex in December 2025 and have changed steadily since. This guide is written against the Codex CLI and desktop behavior as of June 2026. The real source of truth is the
/skillslist in your current session and the official Agent Skills docs.
What a skill actually is
A skill turns a workflow you keep re-explaining into a discoverable capability. Instead of pasting the same “here’s how we do release checks” prompt every week, you write it once as a SKILL.md, drop it in a skills folder, and call it by name.
The mechanism that makes this cheap on context is progressive disclosure. At startup Codex reads only the metadata of every skill it can see (name, description, file path). According to OpenAI’s docs that index is capped at roughly 2% of the model’s context window, or 8,000 characters when the window is unknown, so even dozens of skills cost almost nothing until used. Only when Codex selects a skill does it read the full SKILL.md instructions and any referenced files.
What /skills does
| Item | What it does |
|---|---|
/skills | Opens an interactive picker of skills visible to the current session; the one you choose is inserted as context for your next request. |
$skill-name | Mentions a skill by name directly in your prompt to force it. Requires you to know the name. |
| Implicit selection | Codex loads a skill on its own when your task clearly matches the skill’s description. |
SKILL.md | The instruction entry point: YAML frontmatter plus Markdown steps. |
| Skill assets | Optional scripts/, templates/, and references/ the workflow can use. |
/skills does not run every skill and does not install skills. It is a discovery surface: it shows what is available in this session and lets you pick one to apply.
Where Codex looks for skills
Codex discovers skills from several scopes, nearest-first. As of June 2026 the standard locations are:
| Scope | Path | Use for |
|---|---|---|
| Repo (nearest) | .agents/skills/ | Folder- or module-specific workflows |
| Repo (parent) | ../.agents/skills/ | Nested project layouts |
| Repo (root) | $REPO_ROOT/.agents/skills/ | Skills shared across a whole repo/team |
| User | $HOME/.agents/skills/ | Your personal cross-repo skills |
| Admin | /etc/codex/skills/ | Org-wide system defaults |
| System | Bundled with Codex | OpenAI-provided built-ins |
A few practical notes: duplicate skill names do not merge, both copies show up in the picker, so keep names unique. Symlinked skill folders are supported, which is handy for sharing one canonical skill set across machines. If a skill is missing from /skills, it is almost always in a path Codex cannot see or its plugin is not enabled.
Skill vs AGENTS.md vs prompt vs MCP vs plugin
These five customization layers overlap, so pick by intent:
| Goal | Use | Why |
|---|---|---|
| Persistent project rules | AGENTS.md | Repo conventions, test commands, style, off-limits paths. Always-on, not a workflow. |
| A reusable multi-step workflow | skill | Release QA, SEO audit, render verification. Loaded on demand. |
| One short instruction | a plain prompt | Too small for a skill. |
| Connect external systems | MCP | Browser, database, GitHub, internal APIs. |
| Distribute skills + tools as a set | plugin | A packaged capability bundle for a team or marketplace. |
| Find available skills | /skills | Browse and select what is loaded. |
Rule of thumb: if the workflow needs steps, constraints, examples, and maybe scripts, make it a skill. If it is one sentence of standing policy, put it in AGENTS.md. If it is a one-off, just say it. (Note: Codex’s older standalone custom-prompts feature is now deprecated in favor of skills for reusable instructions.)
Common skill types
| Type | What it is | Examples |
|---|---|---|
| Built-in / system | Bundled with Codex or the host environment, usually read-only | imagegen, doc-lookup skills |
| Plugin skills | Provided by an enabled plugin, often with MCP tools or artifact workflows | browser, documents, presentations, spreadsheets |
| User skills | Custom workflows in $HOME/.agents/skills/ | release-check, seo-audit |
| Project skills | Repo-scoped, committed and team-shared | repo-qa, design-system-review |
What a skill looks like on disk
release-check/
SKILL.md
scripts/
check-links.mjs
templates/
pr-description.md
references/
release-policy.mdA minimal SKILL.md:
---
name: release-check
description: Use when the user asks to prepare a release, verify the changelog or version, run pre-release tests, or produce a go/no-go checklist.
---
# Release Check
1. Read AGENTS.md and package scripts.
2. Inspect git status and changed files.
3. Run the repo's fastest relevant tests first.
4. Verify changelog, version, and migration notes.
5. Produce a release checklist with blockers first.Essentials:
- Keep
nameshort, stable, and memorable; it is what you type after$. - The
descriptiondecides whether Codex picks the skill implicitly, so frontload trigger phrases and state the scope. Avoid marketing words like powerful or automated. - The body defines steps, constraints, and output format.
- Put runnable code in
scripts/, fill-in files intemplates/, and longer policy inreferences/so the mainSKILL.mdstays short.
How to invoke a skill
| Invocation | Example | Best for |
|---|---|---|
Explicit $ mention | Use $release-check to prepare this PR. | You know the exact skill name. |
Pick from /skills | Type /skills, then choose | You forgot the name or want to browse. |
| Natural trigger | ”Prepare a pre-release check.” | The description is clear enough for implicit selection. |
| With files | Use $seo-audit on these MDX files. | The skill must inspect specific files. |
| With tools | Use $browser to inspect localhost:4321. | The skill needs browser, docs, or sheet tools. |
A reliable invocation pattern keeps scope and output explicit:
Use $release-check on the current repo.
Scope: changed files only.
Output: blockers first, then commands run, then remaining risks.
Do not commit unless I ask.Writing a description Codex will actually trigger
The description is the single most important field, because implicit selection matches on it. Write the trigger, not the pitch.
| Weak | Strong |
|---|---|
Helps with releases. | Use when the user asks to prepare a release, verify changelog/version, run pre-release tests, or produce a go/no-go checklist. |
SEO skill. | Use for auditing MDX article metadata, internal links, canonical slugs, hreflang, thin sections, and sitemap readiness. |
Documents. | Use when creating, editing, redlining, or visually verifying .docx documents. |
A strong description includes trigger phrases, boundaries, and the expected output type.
Skill design checklist
| Check | Question to answer in the skill |
|---|---|
| Trigger | When should Codex use it? |
| Boundary | What should it never touch? |
| Input | What files, links, or data are required? |
| Output | What should the final result look like? |
| Tools | Does it need browser, spreadsheet, document render, or MCP tools? |
| Verification | How do we know it finished correctly? |
| Risk | Could it edit files, run commands, cost money, or expose data? |
What should not be a skill
- One-off tasks you will not repeat.
- Tiny preferences like “answer briefly” (those belong in
AGENTS.mdor the prompt). - Fast-changing temporary business data.
- Secrets, tokens, passwords, or customer data.
- Final high-stakes legal, medical, financial, or ethical decisions.
Sharing skills with a team
Because project skills live in $REPO_ROOT/.agents/skills/, they get committed and reviewed like any other code. Treat them that way:
| Practice | Why it matters |
|---|---|
| Version it | Review skill changes in PRs; a bad SKILL.md is a bad instruction for everyone. |
| Assign an owner | Every skill needs a maintainer. |
| Define forbidden areas | Name the paths and commands the skill must avoid. |
| Start read-only | Ship an audit-only version first, allow edits later. |
| Include examples | Add 2-3 real invocation examples to the body. |
| Prune stale skills | An outdated skill is worse than no skill. |
To distribute a skill set beyond a single repo, or bundle it with tools, package it as a plugin. As of June 2026, Codex CLI exposes plugin management commands such as codex plugin list --json and a marketplace, so internal skill bundles can be published and updated like dependencies.
FAQ
Why is my skill missing from /skills?
It is usually in a path Codex cannot see. Confirm the file is SKILL.md (exact name) inside one of the recognized scopes, for example $HOME/.agents/skills/your-skill/SKILL.md or $REPO_ROOT/.agents/skills/.... For a plugin-provided skill, confirm the plugin is enabled in the current session.
Can a skill run commands on its own?
A skill is instructions plus resources, not a permission grant. Whether Codex actually runs a command still depends on your approval policy (/permissions) and your request. A skill cannot bypass approvals.
Do I have to use $skill-name?
No. $skill-name forces a specific skill, /skills opens the picker, and a clear description lets Codex select implicitly from plain wording. Use $ when you want certainty.
How is a skill different from a prompt library? A prompt is text. A skill is a loadable workflow package: instructions plus optional scripts, templates, references, and tool guidance, with progressive disclosure so it costs context only when used.
Are Codex skills the same as Claude Code skills?
The concept is similar (on-demand workflow instructions in a SKILL.md), and Claude Code uses a comparable format. But the discovery paths, slash commands, and plugin systems differ. Codex looks in .agents/skills/; do not assume Claude Code’s directory layout or commands transfer unchanged.
Should I migrate my old custom prompts to skills? Yes. Codex’s standalone custom-prompts feature is deprecated; reusable instructions are now expected to live as skills, which Codex can invoke explicitly or implicitly.
First skills worth building
| Skill | What it does |
|---|---|
repo-tour | Codebase tour: architecture, key directories, test entry points. |
bug-audit | Trace call paths to find a bug before editing anything. |
release-check | Pre-release tests, version, changelog, and a risk list. |
seo-mdx-audit | Metadata, internal links, slugs, and thin-content review for MDX sites. |
test-generation | Read the existing test style first, then add minimal tests. |
migration-plan | Plan phases and rollback points before a large change. |
For deeper background, OpenAI’s own Agent Skills documentation and Codex slash-command reference cover the current field names and command list.
Related
- Every Codex Keyboard Shortcut
- Codex Beginner Guide
- Codex for Code Review
- Codex vs Claude Code
- AI Coding Context Management
Tags: #AI coding #Codex #Skills #Tutorial