Install and load an agent skill in Codex

We installed a small test skill, explain-error, into a Codex CLI project two ways, on two documented project paths, and confirmed with the tool trace (not just the answer text) that Codex actually read the skill’s files before answering. On Codex CLI 0.157.1, both paths worked.

What you need

• Codex CLI installed. We recorded codex --version → codex-cli 0.157.1.
• A disposable git repository to test in.
• Node and npx, for the skills CLI (npx skills, v1.7.0 as tested) and, optionally, the format checker (npx skills-ref, v0.1.5).

The skill we installed

explain-error/SKILL.md has plain frontmatter:

name: explain-error
description: Explains a pasted error message or stack trace and suggests one concrete fix. Use when someone shares an error, exception, stack trace, or traceback and asks what is wrong or how to fix it.

Its body tells the agent to open with the exact line Checked with explain-error, read references/checklist.md in the skill folder and follow it, name the file and line, name the error type and cause, and give exactly one fix. Because references/checklist.md restates that checklist, a checklist-consistent answer alone doesn’t prove the reference file was read. Our broken-reference test below shows Codex can give the same answer even when that read fails. The tool trace, not the answer, is what shows whether the file was actually read.

Two project paths, tested separately

Codex’s current docs name .agents/skills/<name>/SKILL.md. An older OpenAI changelog names .codex/skills/<name>/SKILL.md. We tested both, one at a time, each in its own scratch repository, so a duplicate name couldn’t mask which path actually loaded.

Path A: .agents/skills/

mkdir -p .agents/skills
cp -R /path/to/explain-error .agents/skills/explain-error
codex exec --skip-git-repo-check -s read-only \
  "List the names and descriptions of every skill you currently have available."

Path B: .codex/skills/, in a separate repo

mkdir -p .codex/skills
cp -R /path/to/explain-error .codex/skills/explain-error
codex exec --skip-git-repo-check -s read-only \
  "List the names and descriptions of every skill you currently have available."

Both listings included explain-error with its description. We then ran a matching prompt (a Python AttributeError traceback, “what’s wrong with this?”) and a non-matching one (“Write a haiku about tea.”) against each path.

On the matching prompt, Codex’s trace showed cat calls against both SKILL.md and references/checklist.md, and the answer opened with Checked with explain-error, named the file and line, named the error type, and gave one fix. On the haiku prompt, Codex answered with only a haiku: no marker line, no cat of the skill files. Path B behaved identically to Path A: on this version, the older .codex/skills/ path is not dead, and both paths are live at once.

Installing with npx skills add

The third-party skills CLI can install the same folder from a local path:

npx skills add /path/to/explain-error -a codex -y

This wrote a full copy (not a symlink) to .agents/skills/explain-error/, including references/checklist.md, plus a skills-lock.json recording the source and a content hash. npx skills list afterward reported the skill at .agents/skills/explain-error, listing Codex among the agents that document that path. That line names an installer path convention, not proof every listed agent loaded it. Running the same matching prompt against this copy produced the same trace and marker line as the hand-copied version.

How to confirm the skill loaded

Don’t stop at “the file is on disk” or “it printed the marker line”: either can happen without the skill really being read. Three checks together are enough:

1. Discovery. Ask Codex to list its available skills and confirm the name and description appear.
2. The trace, not just the answer. Look for cat (or equivalent) calls against the skill’s SKILL.md and any reference files it names, on a prompt that should trigger it.
3. A negative prompt. An unrelated request should produce no marker line and no read of the skill’s files. Without this, you can’t tell a real trigger from a skill that always fires.

What we checked

Format

npx skills-ref validate ./explain-error → Valid skill: ./explain-error (exit 0), checked September 27, 2026.

Installs

Both .agents/skills/explain-error/ and .codex/skills/explain-error/ populated correctly by hand-copy. npx skills add -a codex additionally confirmed for .agents/skills/explain-error/; it doesn’t target .codex/skills/.

Loads

On Codex CLI 0.157.1, both project paths were discovered, the matching prompt triggered a read of SKILL.md and references/checklist.md (visible in the trace) and produced the correct marker line, file/line, cause and fix; the non-matching prompt triggered neither.

Helps

Not measured. We confirmed activation, not a paired comparison of answer quality with and without the skill.

What we didn’t check: the personal-scope paths ~/.agents/skills and ~/.codex/skills, the Codex IDE extension, and the desktop app’s Skills view. We also didn’t test Claude Code or Cursor here. See where agent skills live.

Common problems

.agents/skills versus .codex/skills looks like a conflict, and it partly is: OpenAI’s current docs name .agents/skills, while an older changelog names .codex/skills. Both worked in our test on codex-cli 0.157.1. Treat this as a version-specific result, not a permanent guarantee, and re-check on the Codex version you’re running.

A broken reference file can fail silently. When we deliberately renamed references/checklist.md, Codex’s trace showed the failed read, but the final answer gave no sign anything was missing; it fell back on instructions already in SKILL.md. skills-ref validate doesn’t catch this either; it only checks frontmatter shape.

Two skills with the same name aren’t merged: Codex’s docs say both may appear in selectors, so a leftover test skill can shadow or duplicate the one you meant to install.

Editing a skill doesn’t always show up immediately. Codex documents automatic detection of edits, with a restart advised if a change doesn’t appear.

Sources

• OpenAI Docs: Build skills
• OpenAI changelog
• vercel-labs/skills README
• vercel-labs/skills releases