How Codex CLI discovers skills: the .agents filesystem layout

Skills are how you teach OpenAI Codex a reusable workflow, and the part the official docs answer tersely is where the files live, and in what order the agent finds them. I checked the documented behavior against my own setup today; the full layout is below.

The scan order

Codex walks the filesystem from your current working directory upward to the repository root, then checks two global locations. Five levels in total:

$CWD/.agents/skills          current folder
$CWD/../.agents/skills       each parent folder, walking up
$REPO_ROOT/.agents/skills    repository root
$HOME/.agents/skills         user level, all projects
/etc/codex/skills            system level, all users

A skill can therefore be committed with a repository, follow you across projects from your home directory, or be installed machine-wide. One limitation noted in the docs: “If two skills share the same name, Codex doesn’t merge them; both can appear in skill selectors.” Name collisions across levels produce duplicates, not overrides. Prefix project skills if you also keep a large personal set.

What a skill is on disk

A skill is a folder containing a SKILL.md file. Frontmatter needs two mandatory fields, name and description; the body is the instructions the agent follows. Optional additions: a scripts folder, a references folder, assets, and an agents/openai.yaml for extra metadata.

Loading is lazy, which the docs call progressive disclosure: “Codex starts with each skill’s name, description, and file path. Codex loads the full SKILL.md instructions only when it decides to use a skill.” Your context window pays for descriptions up front and for full instructions only on use, so the description line does the selection work. It is better written as a trigger condition than as a summary.

How skills are invoked

Two mechanisms: (1) explicitly, when you invoke /skills or mention $skillname in a prompt, and (2) implicitly, when the agent decides a task matches a skill’s description. There is also a third way to create them that I have not put through serious use yet: record and replay, where you demonstrate a workflow and Codex “records the workflow, inspects the steps, and drafts a reusable skill from the demonstration.” Whether the drafted skill still works on a second, slightly different run is the open question; that experiment is on the list below.

The portability finding

The portability holds one level up from Codex. The SKILL.md shape, a folder with markdown instructions under name-and-description frontmatter, is the same shape Claude Code uses for its skills. The two agents disagree only on the directory (.agents/skills versus .claude/skills) and minor metadata. In practice, however, a workflow written once needs a copy step rather than a rewrite; I keep a small sync script that mirrors skill definitions from one tree to the other, and the mirrored copies have not needed hand editing so far. Convergence on instruction files (AGENTS.md) is widely noticed. In addition, the same convergence is happening one layer up, at the workflow level, and it makes the dual-agent setup less costly to maintain than it appears.

Next test, dated 2026-07-05: I will run record-and-replay on a three-step release workflow and diff the drafted SKILL.md against the version I would write by hand.