Agent Skills
Codex
How Codex finds, installs and reads a skill, from its own docs, checked 26 Oct 2026.
Where it looks for skills
| Scope | Folders 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:
| Rule | Agent Skills spec | OpenAI (Codex & API) |
|---|---|---|
| One SKILL.md per skill | Warns | Fails |
| The zip holds one folder named after the skill | Not checked | Fails |
| Within OpenAI's upload limits | Not checked | Fails |
| The skill sits one folder below its skills folder | Warns | Not checked |
| The name matches its folder | Fails | Warns |
| The name avoids the reserved words anthropic and claude | Warns | Not checked |
| The name says what the skill does | Notes it | Not checked |
| The description has no angle brackets | Warns | Not checked |
| The description says when to use the skill | Notes it | Not checked |
| Has a license field | Notes it | Not checked |
| allowed-tools is one space-separated string | Warns | Notes it |
| No install records in metadata | Warns | Not checked |
| The body is at most 500 lines | Warns | Not checked |
| The body is under about 5,000 tokens | Warns | Not checked |
| Reference files are linked from SKILL.md | Notes it | Not checked |
| Long reference files start with contents | Notes it | Not checked |
| No dated instructions | Notes it | Not 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.