Agent Skills

Codex

How Codex finds, installs and reads a skill, from its own docs, checked 26 Oct 2026.


Where it looks for skills

ScopeFolders it reads
This project.agents/skills/
All your projects~/.agents/skills/

From Codex’s own docs, checked 26 Oct 2026.


Install a skill

  • Copy the skill’s folder, with its SKILL.md at the top, into .agents/skills/ in your project, or into ~/.agents/skills/ for all your projects.
  • Keep the folder named exactly as the name field in its SKILL.md, as The skill folder explains.
  • On qai.io/skills, every skill’s page has the steps for Codex, starting from Install skills in Codex.

Fields it reads

Only the six fields every SKILL.md can hold; its docs name no fields of its own.

SKILL.md sets out the six fields and their limits.


How the format check reads it

The format check on qai.io/skills reads a skill for Codex as OpenAI (Codex & API): Codex finds SKILL.md by its exact name and needs a description; OpenAI's Skills API checks the frontmatter against the spec and caps uploads.

Where that differs from the Agent Skills spec row, rule by rule:

RuleAgent Skills specOpenAI (Codex & API)
One SKILL.md per skillWarnsFails
The zip holds one folder named after the skillNot checkedFails
Within OpenAI's upload limitsNot checkedFails
The skill sits one folder below its skills folderWarnsNot checked
The name matches its folderFailsWarns
The name avoids the reserved words anthropic and claudeWarnsNot checked
The name says what the skill doesNotes itNot checked
The description has no angle bracketsWarnsNot checked
The description says when to use the skillNotes itNot checked
Has a license fieldNotes itNot checked
allowed-tools is one space-separated stringWarnsNotes it
No install records in metadataWarnsNot checked
The body is at most 500 linesWarnsNot checked
The body is under about 5,000 tokensWarnsNot checked
Reference files are linked from SKILL.mdNotes itNot checked
Long reference files start with contentsNotes itNot checked
No dated instructionsNotes itNot checked

Validate a SKILL.md shows what Codex will reject in your file, with the fix.


Watch out for

  • Codex also reads the older ~/.codex/skills folder and does not merge same-named skills, so a skill in both folders shows up twice.
  • It reads .agents/skills in every folder from where you start it up to the repository root.
  • Display name, icon and implicit invocation are set in agents/openai.yaml next to SKILL.md, not in the frontmatter.
  • Machine-wide skills go in /etc/codex/skills.