Codex Skills: a practical guide

AISkills.guru is independent and is not affiliated with OpenAI. Confirm specifics against OpenAI's official skills documentation.

Codex is OpenAI's software-development agent, and it supports the open Agent Skills format. A Codex skill is a folder of instructions and optional resources that Codex can load when a task calls for them — handy for codifying how your team ships code, runs reviews, or works with internal tooling.

This guide covers what a Codex skill is and how it activates. For the format itself, see What are AI Agent Skills? and the SKILL.md guide.

What a Codex skill is

A Codex skill is a directory containing a SKILL.md file. The file's metadata tells Codex when the skill is relevant, and its body holds the steps Codex follows once activated. Skills are reusable across tasks and sessions, so you write a workflow once instead of re-explaining it each time.

Skill directory structure

Codex skills use the standard Agent Skills layout:

my-codex-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/

Only SKILL.md is required. The optional directories add executable code, supporting docs and static resources. This is the same structure described in the SKILL.md guide.

SKILL.md

The file's frontmatter holds at least a name and a description; the body holds the instructions. Because the description drives activation, it should state clearly what the skill does and when to use it.

Explicit invocation

You can ask for a skill directly by name or intent — for example, "use the release-notes skill". Explicit invocation is useful when you know exactly which workflow you want and don't want to rely on automatic matching.

Implicit invocation

Codex can also activate a skill implicitly: when a task matches a skill's description, the skill loads without being named. Implicit activation depends entirely on how well the description is written, which is why specific, trigger-oriented descriptions matter so much. The creation guide covers writing them.

Skill descriptions

A strong description names the trigger conditions and the scope:

Review a pull request against the team's checklist. Use when asked to review code, a PR, or a diff.

A weak description ("helps with code") is unlikely to activate. Treat the description as the skill's entire pitch during discovery.

Scripts, references and assets

• Scripts — code Codex can run (a linter, a generator, a wrapper around an internal CLI).
• References — documents Codex reads selectively, keeping large material out of context until needed.
• Assets — templates and static files the skill produces or consumes.

Because scripts run for real, inspect them before use; the security guide details what to check.

Good use cases for Codex skills

Codex skills shine for repeatable engineering workflows:

• Enforcing a consistent PR review or test checklist.
• Generating release notes or migration scripts in a standard format.
• Wrapping an internal tool or runbook the agent wouldn't otherwise know.
• Applying team-specific conventions to generated code.

Skills vs persistent project instructions

Persistent project instructions (such as an AGENTS.md or similar project-level guidance) are always in context and apply to every task. Skills are the opposite: mostly dormant, loaded only when a task matches. Use persistent instructions for global rules and skills for targeted workflows. The two work well together.

How this compares to Claude and ChatGPT

Codex uses the same open format as Claude Skills and ChatGPT Skills, so a skill written for one can often be reused in another where the implementations align.

Frequently asked questions

Do Codex skills only work in the CLI? Skills are a format; where they load depends on the Codex surface you're using. Check current docs for supported entry points.

Are Codex skills the same as Agent Skills? Codex skills use the open Agent Skills format. "Codex skill" is the product-specific name.

Can a skill run code? Yes, via scripts in the skill folder — which is exactly why you should review them first.

How do I make a skill activate reliably? Write a specific description with clear triggers. See the creation guide.