OpenAI Skills (Codex CLI + ChatGPT)

Why you'd careThe problem it solves

Your repo has a skills directory that took a week to get right — a release-notes skill, a schema-migration skill, each with a checklist, a reference doc and a script. A teammate works in Codex instead of Claude Code and asks whether they can point their agent at the same folder. The answer is yes at the container level and no at the content level. Codex parses the frontmatter and finds the file. Then the model reads step three of your instructions, which says to run Grep across the migrations directory and confirm with the user before Edit — and none of those are nouns Codex has. Nothing errors. No warning appears. The skill just quietly does something looser than the thing you wrote down.

ConceptWhat it is

An OpenAI skill is the same artefact as an Anthropic Agent Skill: a directory whose entry point is a file named SKILL.md, opening with YAML frontmatter that carries at minimum a name and a description, followed by Markdown instructions. Everything else in the directory — reference documents, a Python script, a template — is just files that the instructions can point at.

What OpenAI adopted is the convention, not a runtime. The loading is done by the harness. Codex scans a skills directory, parses the frontmatter of what it finds, and puts the name and description lines into the model's context as a short menu. The body is not loaded until the model decides the skill applies. That two-stage read is the whole design, and it is why the description line does more work than the instructions do.

The boundary that trips people is where the loading happens. In Codex it lives entirely in the client. OpenAI's API has a path of its own: the Responses API mounts skills on the shell tool's environment, either uploaded to OpenAI's /v1/skills and named by skill_id or inlined as a zip, while Chat Completions has no skills parameter at all, so there reading the folder and putting the text in the prompt is your code's job. Anthropic's API path is similar in shape and different in detail: skills ride the code-execution container, and custom ones must be uploaded to Anthropic's registry before a request can reference them. Same folder on disk, several genuinely different delivery stories — and that difference, not the format, is what decides whether your skill survives a move.

How it worksThe mechanics

Authoring is identical on both sides, which is the entire value proposition.

release-notes/
  SKILL.md
  reference/changelog-format.md
  scripts/collect_merged_prs.py

And the top of SKILL.md:

---
name: release-notes
description: Drafts release notes from merged pull requests since the
  last tag. Use when the user asks for release notes, a changelog entry,
  or a summary of what shipped.
---

## Steps
1. Collect merged pull requests since the last tag.
2. Group them under the headings in reference/changelog-format.md.
3. Write one line per user-visible change. Skip refactors.

At session start the harness walks its skill directories, parses only the frontmatter, and injects one line per skill — name plus description, nothing else. When the model judges from that line that the skill applies, it reads the body. Files under reference/ are read only if the body sends it there. Files under scripts/ are executed rather than read, which is how a 400-line script costs you almost no context.

Discovery and enablement are where the vendors diverge. On Claude Code the paths are settled: ~/.claude/skills/ for personal skills, .claude/skills/ committed in the repo. On Codex they are settled too, and the state recorded at the December 2025 launch — a ~/.codex/skills directory plus an --enable flag taking skills — was wrong on both counts. OpenAI's own docs put skills in .agents/skills: in every directory from the working directory up to the repository root, plus $HOME/.agents/skills for the user, /etc/codex/skills for admins, and the skills bundled with Codex. There is no opt-in flag; skills are on by default, and you switch one off with a [[skills.config]] entry in ~/.codex/config.toml. The 2026 secondary write-ups that named .agents/skills were right; a stale blog post is not a spec.

Execution differs too. In Codex CLI a bundled script runs on your machine under the CLI's own approval model. ChatGPT does not take the folder into a Code Interpreter sandbox: standalone skills run in the ChatGPT desktop app, which hosts Codex, and on ChatGPT web and mobile a skill arrives only bundled inside a plugin.

At a glanceSee it

One SKILL.md folder, two harnesses, and the tool names in the body that do not travel.

Where it runsSurfaces and availability

The old two-layer reading does not survive contact with the docs. Hosted APIs on both vendors now mount skill folders: OpenAI's Responses API attaches them to the shell tool's environment, Anthropic's runs them on the code-execution container after a Skills API upload, and both vendors' managed-agent products attach them to the agent by ID. What actually predicts availability is not "harness or raw API" but whether the surface gives the model a filesystem it can read. Where it does not — Chat Completions, Bedrock's model endpoints, Claude on Vertex — a skill is still a file you will end up inlining by hand.

ExampleIn the real world

Priya has a release-notes skill that works in Claude Code. A teammate on Codex wants it. She copies the folder across and reads the body with fresh eyes.

Step 2 says run Grep for BREAKING across the diff. Step 4 says use the Edit tool to update CHANGELOG.md, then ask the user to confirm before writing. Both name Claude Code machinery: a tool called Grep, a tool called Edit, and a permission prompt only that harness raises. Codex has a shell and its own approval model; it does not have those nouns.

She rewrites the verbs. Search the repository for BREAKING. Update CHANGELOG.md in place. Stop and show the diff before writing. Nothing structural changes — same frontmatter, same script, same reference doc.

On the Codex side the model sees one line in its skill menu, matches it when the teammate types "cut release notes for 4.2", opens the body, runs scripts/collect_merged_prs.py, and produces the same grouped draft. The failure she avoided was the silent kind: with the original wording nothing errors. The model improvises a shell equivalent of Grep, and the confirmation step simply never happens.

Not thisWhat it is often confused with

• Not a fork of the formatthe directory shape and the two load-bearing frontmatter keys are the same. The divergence is in discovery paths, the enablement step, and what tools the body may assume exist.
• Not a Chat Completions featurethere is no skills parameter on OpenAI's Chat Completions API, where skills are something a client program does before it calls the model. The Responses API is the exception: it mounts skills on its shell tool.
• Not AGENTS.mdAGENTS.md is one always-loaded file with no name, no description and no trigger. A skill is named, conditional, and can carry scripts and reference files alongside it.
• Not an MCP servera skill grants no new capability. It is text plus files that the harness already had permission to read and run. If the agent cannot reach the thing at all, a skill will not help.
• Not portable prosethe container ports; the sentences inside usually name one harness's tools, sandbox and approval flow.

LimitsWhen not to reach for it

• The procedure is three lines and always applies.Put it in AGENTS.md and pay the tokens once per session instead of building a triggered artefact.
• You need a capability, not a procedure.Querying a warehouse or hitting an internal API is an MCP server or a function tool; a skill can only describe work the agent could already do.
• You are calling the API directly with no harness and no skills mount.Nothing will read the folder. Assemble the text into your prompt and skip the ceremony.
• You need the step to happen every time.Skill invocation is a model judgement about a description line. If it must fire, put it in code or a hook.
• Your team is split across harnesses and the procedure is tool-heavy.Either write it against verbs rather than tool names, or accept two copies and a drift budget.

RelatedGo deeper