Where Codex CLI skills are stored

For new local skills, use ~/.agents/skills for your own library or .agents/skills inside a repository. Codex scans the repository path from your working directory up to its root. /etc/codex/skills is the administrator location. Older setups may also contain ~/.codex/skills; check the skills your installed client actually lists before moving anything.

By Miguel Silva · Updated 2026-09-12

The folders Codex reads

~/.codex/skills/

A CLI-specific location observed in the original August 2026 setup. Existing installations may use it; prefer the currently documented .agents/skills locations for new personal and project skills.

.agents/skills/

Repository skills. Codex scans this folder in every directory from where you launched it up to the repository root, so a skill can belong to one module or to the whole repo.

~/.agents/skills/

The documented user scope. Same idea as ~/.codex/skills; yours, everywhere; under the agent-neutral folder name.

/etc/codex/skills/

Machine scope. For skills an administrator installs once for every user on the box or in the container.

Codex also includes system skills. Some installations materialize those under a .system directory; they are separate from your own library. Codex supports symlinked skill folders in its documented discovery roots.

~/.codex/skills/
└── release-notes/
    ├── SKILL.md          # name and description in the frontmatter
    └── scripts/          # optional, anything the skill runs

Codex initially loads skill names, descriptions and file paths, then reads the instructions when a skill is used. Its documented listing budget is 2% of the context window, with an 8,000-character fallback when the window is unknown. Large lists can have descriptions shortened or skills omitted with a warning.

Listing what you have

No single command prints every scope, so it is one line per folder. The repository one is worth running from the directory you actually launch Codex in, because that is where the upward scan starts.

ls ~/.codex/skills            # inspect an existing CLI-specific setup
ls ~/.agents/skills           # personal, the documented user scope
ls .agents/skills             # this repository
ls /etc/codex/skills          # installed for everyone on this machine

If two skills share a name across scopes, Codex does not merge them: both can appear in the selector, which is confusing in exactly the way you would expect. Rename one.

Turning a Codex skill off without deleting it

There is a supported switch, and it lives in the config file rather than in the skills folder. Point it at the SKILL.md and set enabled to false; the folder stays where it is.

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

The alternative that works in any agent is to move the folder out of a scanned root and back again when you want it. That is the same move as retiring a Claude Code skill, for the same reason: a skill is only ever a folder, and being loaded is a matter of where it sits.

How this compares with Claude Code

Both use the SKILL.md format, but tool names, scripts and client-specific frontmatter can differ. Review those dependencies before sharing a skill across clients.

• Claude Code uses ~/.claude/skills for personal skills and discovers .claude/skills through project ancestors and nested directories according to its own rules. Do not assume the two clients scan identical roots.
• Both clients defer full skill instructions until needed. Listing budgets and discovery behavior differ, so test each client with the intended skill.
• Claude Code counts how often each skill fires, in ~/.claude.json under skillUsage. Codex exposes no equivalent per-skill counter, so on the Codex side what you can see is what is in the folders.
• Turning one off is a config edit in both, in different files: [[skills.config]] in ~/.codex/config.toml for Codex, skillOverrides in settings.json for Claude Code.

The companion page, "Where Claude Code skills are stored", covers the three Claude locations and the plugin case that explains most missing skills. Between them they are the two halves of the same question, and Loadout reads both sets of folders so you do not have to hold the difference in your head.

Questions

Where does the Codex CLI put a skill it creates for me?

Ask it to use ~/.agents/skills for a personal skill or the project .agents/skills directory for a repository skill. An older skill-creator may suggest ~/.codex/skills; confirm the destination and discovery in your installed client.

What is the difference between .codex/skills and .agents/skills?

The current documentation names .agents/skills for personal and repository skills. .codex/skills is a CLI-specific location found in older setups. Confirm what your installed client lists before relocating an existing skill.

Can I use the same SKILL.md in Codex and Claude Code?

Often, but check client-specific instructions, frontmatter, tools and scripts first. Shared SKILL.md syntax alone does not guarantee that a skill works unchanged in both clients.