Where agent skills live on each host
A comparison of documented Claude Code, Codex, and Cursor skill folder paths, marking which ones we tested by hand and which are documented only.
- Published
- Sep 27, 2026
- Checked
- Sep 27, 2026
- Words
- 725
How far we checked this page
Signed by Dhruva Guptha, Sep 27, 2026. Passing one check says nothing about the next.
- FormatCheckedSKILL.md frontmatter validated with skills-ref v0.1.5; host-independent.
- InstallsCheckedverified by hand for both Codex project paths and the Claude Code project path. Every personal-scope path, and every Cursor path, is documented only.
- LoadsChecked on Codex CLI onlyCodex loaded and used the skill on both its project paths. Claude Code and Cursor loading were not tested — see the per-host breakdown below.
- Codex CLI, checkedcodex-cli 0.157.1 · Sep 27, 2026
- Claude Code CLI, not checked2.1.283 (Claude Code) · Sep 27, 2026 · Claude Code CLI could not authenticate in the non-interactive test setup.
- Cursor, not checkedCursor was not installed in the test environment.
- HelpsNot checkedA with/without task comparison was not run.
Every host reads a SKILL.md inside a skill folder, but where it looks for that folder differs, and “documented” is not the same as “we watched it work.” The table below lists the paths each host’s own docs name, and marks exactly which ones we’ve confirmed by hand versus which we’re repeating from documentation.
Comparison table
| Host | Path | Scope | Status |
|---|---|---|---|
| Codex | .agents/skills/<name>/SKILL.md | project (scanned from the working directory up to the repo root) | Tested. Installed by hand and via npx skills add -a codex; discovered and loaded on codex-cli 0.157.1. |
| Codex | .codex/skills/<name>/SKILL.md | project (older/historical path) | Tested. Also installed and loaded on codex-cli 0.157.1; see install skills in Codex for why this matters. |
| Codex | ~/.agents/skills/<name>/SKILL.md | personal | Documented only. Not installed by us. |
| Codex | ~/.codex/skills/<name>/SKILL.md | personal (older/historical path) | Documented only. Not installed by us. |
| Codex | /etc/codex/skills | admin | Documented only. |
| Claude Code | .claude/skills/<name>/SKILL.md | project | File placement tested. Populated correctly by hand and via npx skills add -a claude-code, on Claude Code 2.1.283. Live discovery and invocation were not tested; our non-interactive test setup couldn’t authenticate. |
| Claude Code | ~/.claude/skills/<name>/SKILL.md | personal | Documented only. Not installed by us. |
| Claude Code | <plugin>/skills/<name>/SKILL.md | plugin | Documented only. |
| Claude Code | .claude/skills/ inside the managed settings directory | enterprise | Documented only. The managed directory itself differs by OS (macOS, Linux/WSL, Windows each have a different path). |
| Cursor | .agents/skills/<name>/SKILL.md or .cursor/skills/<name>/SKILL.md | project | Documented only. Cursor was not installed in our test environment. |
| Cursor | ~/.agents/skills/<name>/SKILL.md or ~/.cursor/skills/<name>/SKILL.md | personal | Documented only. Cursor also documents reading Claude Code’s and Codex’s skill paths for compatibility, which we have not confirmed. |
“Tested” here means we placed a real skill at that exact path, on a recorded host version, and (where marked) watched the host read the skill’s files and use them on a matching prompt. “Documented only” means the path comes from the host’s own docs (linked below), and we have not put a file there ourselves.
What “documented” doesn’t tell you
A path existing in a host’s documentation, or a file sitting at that path, doesn’t establish that the host actually looked there this session. Three things can each be true or false independently:
| Question | Maps to |
|---|---|
| Does the file exist at the documented path? | Installs |
| Do the host’s own docs name that path? | Documentation |
| Did the host actually read the file and use its instructions on a real prompt? | Loads |
Our Codex row satisfies all three, on both its documented project paths, on codex-cli 0.157.1. Our Claude Code row satisfies the first two; the third is still open. Every Cursor row is documentation only.
The one real conflict we could resolve
OpenAI’s current docs name .agents/skills as the project path; an older changelog names .codex/skills. The skills CLI’s own installer table still targets ~/.codex/skills for its Codex agent, which conflicts with the current personal-scope docs too. We tested both project-scope paths side by side on codex-cli 0.157.1, in separate scratch repositories, and both worked identically: discovery listed the skill, and a matching prompt triggered a real read of its files. That resolves the conflict for this specific version. It does not mean the older path is guaranteed to keep working on a future Codex release.
What we checked
Installs
.agents/skills/, .codex/skills/ (Codex, both project scope) and .claude/skills/ (Claude Code, project scope), all confirmed by hand-copy. npx skills add additionally confirmed for .agents/skills/ and .claude/skills/ only; it doesn’t write .codex/skills/.
Loads
Codex only, on both of its project paths, on codex-cli 0.157.1.
What we didn’t check: every personal-scope path in the table, Claude Code’s plugin and enterprise paths, and every Cursor path (Cursor was not installed in our test environment). See install skills in Codex for the full Codex test, and portable agent skills for what changes when you move one skill folder between these paths.