Where Are Codex CLI Skills Stored?

The Codex CLI stores your skills in ~/.codex/skills/ on Unix systems and %USERPROFILE%\.codex\skills\ on Windows. Each skill lives in its own subdirectory with a SKILL.md file that defines what it does.

This directory structure matters more than you might think. Where your skills live affects how the CLI finds them, how updates work, and what happens when you switch between projects.

Default storage locations

Your skills directory depends on your operating system:

# macOS and Linux
~/.codex/skills/

# Windows
%USERPROFILE%\.codex\skills\

# Windows (expanded example)
C:\Users\YourName\.codex\skills\

Inside this directory, each skill gets its own folder named after the skill itself. A typical setup looks like this:

~/.codex/skills/
├── git-commit-helper/
│   ├── SKILL.md
│   └── script.py
├── file-organizer/
│   ├── SKILL.md
│   └── organize.sh
└── api-tester/
    ├── SKILL.md
    ├── test.js
    └── config.json

The SKILL.md file in each directory follows the SKILL.md spec and tells Codex what the skill does, what parameters it accepts, and how to run it.

How Codex finds your skills

When you run a command, Codex scans the skills directory and loads every SKILL.md file it finds. The CLI doesn't recursively search subdirectories, so skills must be exactly one level deep.

This scanning happens on every invocation, which means you can install skills by simply dropping a new folder into the skills directory. No restart required.

The loading order isn't guaranteed, but it doesn't matter since skills should be independent. If you have naming conflicts between skills, Codex will warn you and use the first one it encounters.

Customizing the skills directory

You can override the default location by setting the CODEX_SKILLS_PATH environment variable:

export CODEX_SKILLS_PATH=/path/to/my/skills
codex "help me debug this function"

This works across all platforms and affects both skill loading and where new skills get installed. The directory must exist before Codex tries to use it.

Some developers point this to a version-controlled directory shared across their team:

export CODEX_SKILLS_PATH=~/shared-skills

This way everyone on the team uses the same skill collection without manual syncing.

Project-specific skills

Codex also looks for skills in your current project. If you have a .codex/skills/ directory in your working directory, those skills get loaded in addition to your global ones.

my-project/
├── .codex/
│   └── skills/
│       └── project-specific-helper/
│           └── SKILL.md
├── src/
└── README.md

Project skills take precedence over global skills with the same name. This lets you customize behavior for specific codebases without affecting your general setup.

The search order is:

1. ./.codex/skills/ (current directory)
2. Global skills directory
3. Any path specified by CODEX_SKILLS_PATH

Skills vs other agent tools

Unlike MCP servers that run as separate processes, skills are just files that Codex reads directly. This makes them lighter weight but less capable than full MCP implementations.

Skills also differ from rules files in that skills define actions while rules define constraints. You might have a skill that formats code and a rule that requires all code to be formatted before committing.

The Skills vs MCP comparison goes deeper into when to use each approach.

Backing up and sharing skills

Since skills are just files in a known location, backing them up is straightforward. Many developers symlink their skills directory to a git repository:

mv ~/.codex/skills ~/.codex/skills.backup
ln -s ~/my-skills-repo ~/.codex/skills

This approach version-controls your skills and makes them portable across machines. You can also share skills by pointing colleagues to your repository.

For one-off sharing, you can zip a skill directory and send it. The recipient just needs to extract it into their skills directory.

Troubleshooting skill loading

If a skill isn't working, check these common issues:

The skill directory must contain a valid SKILL.md file. Codex ignores directories without this file, even if they contain other skill-related files.

Syntax errors in SKILL.md prevent the skill from loading. Run codex --list-skills to see which skills Codex successfully parsed.

File permissions matter on Unix systems. Make sure your skills directory and files are readable by your user account.

The SKILL.md format is strict. Missing required fields or malformed YAML frontmatter will cause parsing failures. Check the SKILL.md spec for details.

Managing large skill collections

As your skill library grows, organization becomes important. Some developers group skills into subdirectories, but remember that Codex only looks one level deep.

Instead, use descriptive naming:

~/.codex/skills/
├── git-commit-helper/
├── git-branch-cleaner/
├── docker-compose-debug/
├── api-test-runner/
└── file-backup-organizer/

You can also use the skill metadata to add tags or categories within the SKILL.md files themselves. This doesn't affect loading but helps with documentation and discovery.

For teams, consider splitting skills by domain or project rather than keeping everything in one massive directory. Use CODEX_SKILLS_PATH to switch between skill sets as needed.

The skills directory is simpler than it might seem at first. It's just a folder full of folders, each with a SKILL.md file. That simplicity makes skills easy to understand, share, and debug when things go wrong.