What this covers
This guide explains Codex skills: what they are, why they appear under /skills, how to invoke them, how to write SKILL.md, and when to use a skill instead of a prompt, AGENTS.md, MCP, or a plugin.
Version note: Codex skills, plugins, and desktop capabilities change quickly. This guide is written against the 2026-05-22 Codex desktop / CLI 0.125.x workflow. The real source of truth is the
/skillslist in your current session.
One-sentence definition
A Codex skill is a local bundle of instructions, scripts, templates, or references that Codex can load on demand, turning a repeated workflow into a discoverable and reusable capability.
What /skills does
| Item | Explanation |
|---|---|
/skills | Opens the list of skills visible to the current session. |
$SkillName | Explicitly asks Codex to use a skill by name. |
| Auto-selection | Codex may load a skill when the task clearly matches its description. |
SKILL.md | The instruction entry point for a skill. |
| Skill assets | Scripts, templates, references, and examples that support the workflow. |
/skills is not “run every skill” and not “install skills.” It is a discovery surface for capabilities visible in the current session.
Common skill types in Codex
| Type | Explanation | Examples |
|---|---|---|
| System skills | Built into Codex or provided by the host environment. Usually read-only. | imagegen, openai-docs |
| Plugin skills | Provided by enabled plugins, often with MCP tools or artifact workflows. | browser-use:browser, documents:documents, presentations, spreadsheets |
| User skills | Custom workflows stored in your local Codex skills directory. | release-check, seo-audit |
| Project skills | Repo-scoped skills shared with a project/team. | repo-qa, design-system-review |
| Thread-provided skills | Temporarily provided by the current thread/environment. | Workspace-specific export or review workflows |
Skill vs. AGENTS.md vs. slash command vs. MCP vs. plugin
| Goal | Use | Explanation |
|---|---|---|
| Persistent project rules | AGENTS.md | Repo conventions, test commands, style, boundaries. |
| Reusable workflow | skill | Release QA, SEO audit, render verification. |
| One prompt snippet | prompt/snippet | Too small for a skill. |
| Connect external systems | MCP | Browser, database, GitHub, internal APIs. |
| Ship skills plus tools | plugin | A packaged capability set for a team. |
| Discover available skills | /skills | Browse and select visible skills. |
Rule of thumb: if the workflow needs steps, constraints, examples, and maybe scripts, make it a skill. If it is one sentence, keep it as a prompt.
What a skill looks like
my-skill/
SKILL.md
scripts/
check-links.mjs
templates/
pr-description.md
references/
release-policy.mdMinimal SKILL.md:
---
name: release-check
description: Run this skill when the user asks to prepare a release, verify changelog, run tests, or create a release 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. descriptionshould say when to use it, not market it.- Body should define steps, constraints, and output format.
- Put scripts in
scripts/, templates intemplates/, long references inreferences/.
How to invoke a skill
| Invocation | Example | Best for |
|---|---|---|
| Explicit mention | Use $release-check to prepare this PR. | You know the exact skill. |
Pick from /skills | Type /skills, then choose | You forgot the name. |
| Natural trigger | ”Prepare a pre-release check.” | The description is clear enough. |
| With files | Use $seo-audit on these MDX files. | The skill must inspect files. |
| With tools | Use $browser to inspect localhost. | The skill needs browser/docs/sheets tools. |
Invocation template:
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.How to write a good description
| 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 expected output. Avoid vague words like powerful, efficient, or automated.
Skill design checklist
| Check | Question |
|---|---|
| Trigger | When should Codex use it? |
| Boundary | What should it avoid? |
| Input | What files, links, or data are required? |
| Output | What should the final output look like? |
| Tools | Does it need browser, spreadsheet, document render, or MCP tools? |
| Verification | How do we know it is done? |
| Risk | Could it edit files, run commands, cost money, or expose data? |
What should not be a skill
- One-off tasks.
- Tiny preferences like “answer briefly.”
- Fast-changing temporary business data.
- Secrets, tokens, passwords, customer data.
- Final high-stakes legal, medical, financial, or ethical decisions.
Team-sharing guidance
| Practice | Note |
|---|---|
| Version it | Review skills like code. |
| Assign owner | Every skill should have a maintainer. |
| Define forbidden areas | Name paths/commands the skill must avoid. |
| Start read-only | Audit first, allow edits later. |
| Include examples | Add 2-3 real invocation examples. |
| Prune stale skills | Old skills become bad instructions. |
FAQ
Why is my skill missing from /skills?
Check whether it is installed in a path visible to Codex, whether the plugin is enabled, and whether the current session has loaded that capability. For a project skill, confirm the repo path and the skill directory are both visible to Codex.
Can a skill run commands automatically? A skill is instructions plus resources. Command execution still depends on Codex tools, approval policy, and your request. A skill is not a permission bypass.
How is a skill different from a prompt library? A prompt is text. A skill is a reusable workflow package that can include instructions, resources, scripts, and tool guidance.
Do I have to use $SkillName?
The $ form is a clear explicit mention. /skills is the discovery entry point. Natural language can also work when the description is clear.
Are Codex skills the same as Claude Code skills?
The idea is similar: on-demand workflow instructions. The host tool, directory conventions, plugin system, and slash commands may differ. Do not copy Claude Code’s /commands, hooks, or directory structure directly into Codex.
First skills to build
| Skill | Use |
|---|---|
repo-tour | Codebase tour: architecture, directories, test entry points. |
bug-audit | Bug audit through call paths before editing. |
release-check | Pre-release tests, version, changelog, risk list. |
seo-mdx-audit | Metadata, links, slugs, and thin-content review for MDX sites. |
test-generation | Read existing test style, then add minimal tests. |
migration-plan | Plan phases and rollback points before large changes. |
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