Codex Skills: Install, Use, and the Best Picks

A Codex skill is a folder containing a SKILL.md file that teaches OpenAI's Codex agent how to do a specific job — draft a PR, run your test suite, follow your team's review checklist. Codex reads each skill's name and description, then loads the full instructions only when the task calls for it. If you searched for "Codex skills," here is what they are, how to install one, how Codex decides to use it, and where to find good ones.

What a skill is (and how it differs from a prompt)

A skill is a directory anchored by a required SKILL.md manifest — a Markdown file with YAML frontmatter (at minimum a name and a description) followed by step-by-step instructions. Alongside SKILL.md, a skill can bundle optional scripts, reference files, and assets the workflow needs.

This is a step up from the older custom prompts. A prompt was a single file you triggered by hand. A skill is discoverable: Codex indexes the metadata of every skill it finds and can pick the right one on its own. OpenAI now points new reusable workflows at skills rather than custom prompts. Skills also follow the same open SKILL.md format used across the agent ecosystem, so a well-written skill is portable.

Where skills live

Codex looks for skills in a few places, in priority order:

• Project — .agents/skills/ inside a repository. Check these in so your whole team gets them.
• User — ~/.agents/skills/ (that is $HOME/.agents/skills/). Your personal skills, available in every project.
• System / built-in — skills shipped with Codex.

When two skills share a name, the project one wins over your user one, which wins over system defaults. That lets a repo override a personal skill for its own conventions.

Installing a skill

A skill is just a folder, so installing one is copying that folder into a skills directory. To add a personal skill:

mkdir -p ~/.agents/skills/pr-review

Create ~/.agents/skills/pr-review/SKILL.md:

---
name: pr-review
description: Review a pull request diff for bugs, security issues, and missing tests
---

When asked to review a PR:
- Summarize what the diff changes in two sentences.
- Flag bugs and security issues first, with file and line.
- Note any public function that gained behaviour but no test.
- Keep style nits to a short, separate list.

Codex detects new skills automatically; if the new one does not show up, restart Codex. To share a skill with your team instead, put the same folder under .agents/skills/ in the repo and commit it.

Using a skill

Codex offers three ways to trigger a skill:

• Automatic. Describe your task normally. If it matches a skill's description, Codex runs that skill on its own. This is the payoff of the metadata-first design.
• Explicit. Reference the skill by name with a $ prefix in your prompt — for example $pr-review this branch. Use this when you want a specific skill for certain.
• Browse. List the available skills with the /skills command and pick one.

Because Codex only reads names and descriptions until a skill is invoked, a sharp, specific description is the single most important line in your SKILL.md — it is what makes the skill discoverable at the right moment.

Writing a skill Codex actually reaches for

• Make the description a trigger, not a title. "Review a PR diff for bugs and missing tests" beats "Code review helper." Codex matches on it.
• Keep the body prescriptive. Concrete steps and output format, not vague encouragement.
• Push detail into files. Long checklists or scripts belong in sibling files the skill references, so the manifest stays scannable.
• One job per skill. A skill that tries to do everything is hard to match and hard to trust.

Skills vs AGENTS.md

Codex has a second way to carry instructions: AGENTS.md. It works as a hierarchy — a global ~/.codex/AGENTS.md, an AGENTS.md at your repo root, and optional ones in subdirectories — and its contents are always-on context for that scope. A skill is the opposite: scoped, and pulled in only when its description matches or you call it. Use AGENTS.md for standing conventions that apply to everything ("this repo uses pnpm, TypeScript strict, Conventional Commits"), and skills for named workflows you trigger on demand. They complement each other: broad guardrails in AGENTS.md, specific playbooks in ~/.agents/skills/.

The best Codex skills to start with

You do not have to write everything yourself. For a curated shortlist of Codex skills worth installing, see our best Codex skills picks. To browse by task — testing, review, refactoring — start from the skills catalog or the development category. Since the SKILL.md format is shared across agents, many skills written for other tools drop into ~/.agents/skills/ with little or no change.

Skills turn Codex from a general assistant into one that follows your playbook. Start with one skill for your most repetitive task, get its description right, and add more as the pattern proves itself.