Skills

Install skills in Codex

Codex looks for skills in .agents/skills/ in a project, and in ~/.agents/skills/ for all your projects.

Where Codex looks for skills

This project

  • .agents/skills/

All projects

  • ~/.agents/skills/

Source: learn.chatgpt.com (opens in a new tab), checked 26 Oct 2026.

Install a skill

  1. 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.
  2. Keep the folder named exactly as the name field in its SKILL.md, as the Agent Skills spec asks.
  3. Or use the Codex tab on any skill's page here: its commands copy that skill at the commit we checked.

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.

Where every other agent looks for skills