Codex Skills: Turn Repeated Workflows Into AI Playbooks

You vibe-coded a win last week. You described what you wanted, the agent built it, it worked, you shipped. Then on Monday you needed the same thing again, the same release ritual, the same onboarding steps, and you typed the whole paragraph out from scratch. Again.

That gap is what Codex skills close. A skill is a reusable playbook the agent reads only when a task matches it, so the thing you figured out once becomes a one-line trigger from then on. OpenAI shipped agent skills for Codex as reusable bundles of instructions, plus optional scripts and resources, that help Codex reliably complete specific tasks. This guide covers what they are and how to write your first one, folder tree and frontmatter included, whether or not you write code.

What an agent skill actually is

A skill is a folder. Inside it lives one file, SKILL.md, written in plain Markdown. That is the whole floor:

release/
  SKILL.md

And the file itself:

---
name: release
description: Use when cutting a new release. Bumps the version,
  updates the changelog, runs the test suite, drafts release
  notes, and tags the commit. Trigger on "ship a release" or
  "cut version".
---

# Release playbook

1. Bump the version in package.json (patch unless told otherwise).
2. Move everything under "## Unreleased" in CHANGELOG.md into a
   new dated version heading.
3. Run `npm test`. If anything fails, stop and report. Do not tag.
4. Draft release notes from the changelog entries, grouped by
   Added / Fixed / Changed.
5. Create an annotated git tag matching the new version.

The YAML frontmatter requires exactly two fields, name and description. The body is just instructions, in the order you would give them to a careful new hire. No JSON schema, no SDK, no build step. A non-technical founder can write that in five minutes.

When a skill outgrows one workflow, you add optional subfolders: scripts/ for helper code it can run, references/ for longer docs, assets/ for templates, and an agents/openai.yaml for Codex-specific config. None of it is required to start.

How skills differ from prompts and from AGENTS.md

A prompt is a one-shot instruction. You type it, the agent acts, the words evaporate. Next time you need the same outcome, you reconstruct the prompt from memory and get it slightly wrong, because you always do.

A skill is the prompt made durable and self-selecting. The difference comes down to that description field. Codex reads the name and description of every installed skill up front. When you describe a goal, it matches your request against those descriptions and loads the right playbook on its own. You say "ship a release," Codex notices the release skill's description mentions exactly that, and pulls it off the shelf.

Skills are not AGENTS.md, though builders mix these up constantly. AGENTS.md is always-on project context, the house rules Codex reads on every task ("we use pnpm, never npm; tests live in __tests__; never touch /legacy"). Skills load on demand, only when a task matches.

AGENTS.md: the rules the agent always knows.
Skills: the playbooks it pulls off the shelf when the job calls for one.

Put always-needed rules in a skill that rarely triggers and the agent will not follow them. Put a niche release ritual in AGENTS.md and you have bloated the context every task pays for. Right thing, right layer.

How Codex fires a skill

There are two ways to invoke a skill, and the second is the interesting one.

Explicit invocation. You call it by name, with the /skills command or $skill-name syntax, for example $release. Useful when you know precisely which playbook you want.
Implicit invocation. You describe the goal in plain English and Codex auto-selects the matching skill from its descriptions. No command to memorize: you say what you want done, and the right playbook loads itself.

The reason you can install dozens of skills without the agent slowing down is progressive disclosure. Codex initially reads only each skill's name, description, and file path, not the full body. It loads the complete SKILL.md only when it decides to use that skill. Anthropic, which originated the format, calls progressive disclosure the core design principle that makes Agent Skills scalable. A hundred playbooks on the shelf cost almost nothing until one is pulled.

Skills live in scopes that map to who the playbook is for:

Repo-level (.agents/skills in your project): team playbooks, checked into the repo.
Personal ($HOME/.agents/skills): your own playbooks, available across every project.
Admin (/etc/codex/skills): company-standard playbooks an admin sets for a fleet.
Built-in: skills bundled with Codex itself, including helpers that scaffold and install skills for you.

Codex and Claude Code sit on the same standard

Here is the detail worth internalizing: the SKILL.md format is an open, cross-tool standard, not a single vendor's invention. Anthropic originated it with Claude Code's Agent Skills and published it openly for cross-platform portability, and Codex builds on that same standard. The frontmatter, the progressive-disclosure model, and the folder structure are shared, so a release playbook you write is largely portable between OpenAI Codex and Claude Code. You are learning a standard, not betting on a vendor. And skills are not a programmer-only thing: pre-built skills for documents and spreadsheets run from a chat window with no terminal required.

An example skill library

A few playbooks worth stealing, each grounded in something the tools genuinely do:

release/: the version-bump-test-tag ritual above. Codex already reads your repo, edits files, runs tests, and commits, so this skill just makes that loop one-shot.
onboarding/: installs and configures the team's tools so every contributor's agent behaves the same, teaching Codex how you do tickets and setup.
branch-review/: a playbook that orchestrates a team of subagents. One sentence fans out three specialists: "Review this branch against main. Have pr_explorer map code paths, reviewer find risks, and docs_researcher verify APIs."

That last one shows how skills compose with subagents, the specialized agents Codex can spawn in parallel and consolidate into one answer. One honesty note that trips people up: Codex only spawns a subagent when you explicitly ask it to. They do not fire themselves.

Business use cases for non-technical founders

You do not need to read code for any of these.

Consistent customer replies. A support-triage skill that classifies an incoming message, drafts a reply in your brand voice, and flags anything needing a human. Written entirely in Markdown.
Weekly investor update. An investor-update skill that pulls your standard sections, asks for this week's three numbers, and drafts the email in your format.
New-hire setup. An onboarding skill so the first day runs identically every time instead of living in one person's head.

The pattern: anything you explain the same way twice is a candidate for a skill.

Safety and review checklist

Skills add repeatability; they do not add judgment. Run this before you trust one:

Write a description that says when, not just what. Implicit invocation depends on it. A vague description means the skill never fires, or fires on the wrong task.
Do not dump everything into one giant SKILL.md. That defeats progressive disclosure. Split deep content into referenced files.
Keep skills and AGENTS.md in their right layers. Always-on rules in AGENTS.md, on-demand playbooks in skills.
Do not expect subagents to auto-spawn. They do not; you ask. Mind the defaults on thread count and depth.
Build the verify step into the skill. Bake the test command and a "stop on failure" instruction directly into the playbook, because repeatability does not remove the risk of accepting unreviewed output.
Do not assume vendor lock-in. SKILL.md is an open, portable standard. Write it once; run it across tools.

Skills are the maturity step after vibe coding. The vibe gets you the first version; the skill makes it reliable, with a verify gate baked in.

Keep the playbooks

Save your working skills as a versioned set in Command Center, so the workflow you figured out once becomes an asset the whole team reuses.

Sources and further reading

FAQ

Do I need to know how to code to write a Codex skill? No. The required parts of a SKILL.md are plain Markdown: a name, a description, and numbered instructions. Scripts are optional. If you can write a clear how-to for a coworker, you can write a skill.

What is the difference between a skill and AGENTS.md? AGENTS.md is always-on context Codex reads on every task. A skill loads only when a task matches its description. Standing rules go in AGENTS.md; specific repeatable workflows go in skills.

Will a skill I write for Codex work in Claude Code? Largely, yes. SKILL.md is an open standard Anthropic originated and published for portability, and Codex builds on it. The format, frontmatter, and progressive-disclosure model are shared.

Why will not Codex use my skill even though it is installed? Almost always the description. Codex picks skills by matching your request against descriptions, so a fuzzy one loses to a precise one. State when to trigger, not just what the skill does.