How to Create a Codex Skill

The smallest skill that works

A Codex skill is a directory with a SKILL.md in it. Two frontmatter fields are required:

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

Generate release notes for the current repository:

1. Find the most recent tag with `git describe --tags --abbrev=0`.
2. List merged PRs since that tag.
3. Group them into Added, Fixed, and Changed.
4. Write the result to `CHANGELOG.md` under a new heading.

Put it somewhere Codex scans. Personal, available everywhere:

mkdir -p ~/.agents/skills/release-notes

Project-scoped, committed so the team gets it:

mkdir -p .agents/skills/release-notes

Restart Codex, then invoke it with $release-notes — or just ask for release notes and let the description do its job.

Don't use ~/.codex/skills for skills you write. Codex still scans it, but its own source marks that path as deprecated and kept only for backward compatibility. Details in where skills live.

Let Codex write it for you

Codex bundles a skill-creator skill, so there's nothing to install:

$skill-creator

It asks what the workflow does and whether it needs scripts, then writes the files. In ChatGPT Work the same thing is @skill-creator. It's a reasonable way to get the scaffolding right the first time — though the description it produces is still worth editing yourself, for the reason below.

Writing a description Codex actually triggers on

This is the part that matters, and it's constrained by something most guides never mention.

Codex loads only each skill's name and description into context up front, then pulls the full SKILL.md when it decides to use one. That index is capped at 2% of the context window or 8,000 characters, whichever is smaller. Every skill you install competes for that budget.

Two consequences:

Be specific about when it should fire. The official guidance is to "explain exactly when this skill should and should not trigger." A description like Helps with documentation gives Codex nothing to match against and will either never fire or fire constantly.

Write the negative triggers too. The best-written skill in OpenAI's own catalog spends roughly half its description on what should not activate it. security-threat-model reads:

Trigger only when the user explicitly asks to threat model a codebase or path, enumerate threats/abuse paths, or perform AppSec threat modeling. Do not trigger for general architecture summaries, code review, or non-security design work.

That's the model to copy. Name the trigger phrases a user would actually type, then name the adjacent things that should not pull it in.

Beware name collisions. If two installed skills share a name, Codex shows both in the selector without merging or picking a winner. There's no precedence rule to rely on, so give skills distinctive names.

Adding supporting files

SKILL.md is the only required file. The rest of the structure is optional and loads only when the instructions point at it:

my-skill/
├── SKILL.md              # required
├── scripts/              # executable code the skill can run
├── references/           # documentation loaded on demand
├── assets/               # templates, images, resources
└── agents/
    └── openai.yaml       # optional Codex/ChatGPT metadata

Keep SKILL.md itself lean and push detail into references/. That's the whole point of the format — the body only enters context when the skill is actually used, and bulk that's rarely needed belongs one level down.

If your skill ships scripts that reach the network, expect Codex to request escalated sandbox permissions when it runs them. OpenAI's own skill-installer documents exactly this behavior.

Codex-specific metadata

agents/openai.yaml is optional, Codex- and ChatGPT-specific, and does not travel to other agents:

interface:
  display_name: "Release Notes"
  short_description: "Draft release notes from merged PRs"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Optional surrounding prompt"

policy:
  allow_implicit_invocation: false

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"

Two fields earn their keep:

policy.allow_implicit_invocation: false stops Codex triggering the skill on its own, leaving $skill-name as the only way in. Use it for anything with side effects — deploys, publishes, anything that writes to a system you'd want a human to have chosen deliberately.
dependencies.tools declares that the skill needs an MCP server, so the dependency is visible rather than surfacing as a confusing failure mid-run.

Testing it

There's no validation command in the docs, so the practical loop is: restart Codex, confirm the skill appears when you type $, then test both invocation paths separately. Invoke it explicitly with $skill-name to check the instructions work. Then start a fresh session and phrase a request the way a user actually would, without naming the skill, to check the description triggers it. Those are two different failures — instructions that don't work, and a description that doesn't match — and they need fixing in different places.

If it doesn't appear at all, the cause is nearly always the directory or the frontmatter. See the installation troubleshooting table.

Within a repo, commit .agents/skills/<name>/ and you're done. Codex scans that directory in every folder between the project root and the working directory, so a skill at the repo root applies throughout, and a package can carry its own.

Beyond a repo, the picture changed recently. OpenAI's catalog repository, openai/skills, now opens its README with a deprecation notice pointing to openai/plugins, and directs anyone wanting to add skills to Codex toward the Build plugins guide and a skill-only plugin. That's the current intended distribution route, so a guide telling you to open a PR against openai/skills is out of date.

Anyone can also install directly from any GitHub repository without a catalog at all — see installing from a GitHub repo. For a skill you want a handful of colleagues to use, publishing the repo and sharing the command is the lowest-friction option.

Because the format is the shared Agent Skills standard, a skill written this way also works in Claude Code, Hermes Agent, and other compatible agents — with the exception of agents/openai.yaml, which only Codex and ChatGPT read.

Caveats

We have not run Codex or created a skill through it. Everything here is documented behavior or verified in the openai/codex source, and this page distinguishes the two.
The docs describe no formal validation or linting command for skills as of August 2026; the testing loop above is a practical procedure, not an official one.
Codex is changing quickly and its documentation recently moved hosts. Check the official skills docs if you're reading this much later.

Sources

Codex — Build skills (official docs)
openai/codex — bundled skill-creator and skill-installer
openai/skills — security-threat-model SKILL.md — quoted description; catalog read 16 August 2026
openai/plugins — the stated distribution route