How to use skills in Codex: where the folder is and how to call one

Where Codex looks for skills

From OpenAI's Codex docs, read 6 November 2026. Codex follows symlinked skill folders. If two skills share a name, Codex doesn't merge them; both can appear in the list.

Install a skill on Mac or Windows

You have a folder, say crash-triage, with a SKILL.md directly inside, in Downloads.

Mac or Linux, in Terminal:

mkdir -p ~/.agents/skills
cp -R ~/Downloads/crash-triage ~/.agents/skills/

Windows, in PowerShell. OpenAI gives one path, $HOME/.agents/skills, with no separate Windows path, and in PowerShell $HOME is your user folder, the value of %USERPROFILE% (Microsoft's docs):

New-Item -ItemType Directory -Path "$HOME\.agents\skills" -Force
Copy-Item -Path "$HOME\Downloads\crash-triage" -Destination "$HOME\.agents\skills" -Recurse -Force

Point -Path at the folder with SKILL.md directly inside: if Extract All put it one level deeper, as in Downloads\crash-triage\crash-triage, copy the inner one. Copying into the skills folder itself keeps the folder's name, and -Force lets you rerun the line for a newer version.

Codex notices new skills on its own; if one doesn't appear, restart Codex. Then run /skills to check it's listed. Running Codex inside WSL? There it uses the Linux home folder, so copy the skill there instead.

Skills from a repository, such as OpenAI's curated set: ask the built-in installer, for example $skill-installer linear. You can also tell it to download skills from other repositories.

Call a skill, or let Codex pick it

Without a mention, Codex chooses a skill when your request matches its description. With many skills installed, Codex shortens descriptions to fit, so put the main use and the words you'd type at the start of the description.

To turn a skill off without deleting it, add an entry to ~/.codex/config.toml and restart Codex:

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

A worked example: one crash-triage skill for Codex and Claude Code

Illustration: a made-up business. A three-person studio ships a mobile app. Lena works in the Codex CLI on a Mac, Sam in Codex on Windows, and their contractor Ola in Claude Code. Whenever a crash report arrives, Lena pastes:

Here's a crash log. Find the first stack frame in our code, not in the libraries. Tell me the file and line, what the user was doing from the breadcrumbs, how many users and which app versions, and draft an issue titled "[crash] <screen>: <error>".

She gives the prompt-to-skill skill that prompt and two issues she wrote by hand last week, as examples of the output she wants. The start of what it returns:

---
name: crash-triage
description: Triages a mobile crash log - the first stack frame in the team's own code, what the user was doing, affected users and app versions - and drafts the issue. Use when someone pastes a crash log, a stack trace or asks "why is the app crashing".
---

## Steps
1. Skip library and system frames. The first frame in our code is
   the suspect.
2. From the breadcrumbs, write what the user did in one sentence.
...

1. Lena saves it as ~/.agents/skills/crash-triage/SKILL.md and calls it with $crash-triage on the next report.
2. Sam runs the two PowerShell lines above; /skills lists crash-triage.
3. Ola's Claude Code doesn't read .agents/skills. She copies the folder into ~/.claude/skills/ too, so now there are three copies on three computers.

When Lena changes the issue title format, the other two copies keep the old one.

Next step: one copy for Codex, Claude Code and the rest of the team

On one computer, a single folder linked into both ~/.agents/skills and ~/.claude/skills keeps Codex and Claude Code on the same file: syncing skills across Claude Code, Codex, Cursor and OpenCode shows the links. Between people, each copy still drifts.

AI Skill Pod, this site's product, lets you share AI skills with your team, easily; free to start. Each person adds the team's pod once, in Codex with codex mcp add and the pod's link, then codex mcp login, and once in each other AI they use: Claude Code, Cursor, Claude or ChatGPT (Pro, Business, Enterprise). Everyone reaches the same skills, and an edit reaches all of them the next time their AI fetches the skill. The pod's skills don't appear in /skills: Codex fetches them from the pod when a task matches, or when you ask for one by name. Free covers up to 3 members and 10 skills.

Questions

Where are Codex skills stored?

Your own skills go in $HOME/.agents/skills/<skill-name>/SKILL.md and are available in every repository. A repository's skills go in .agents/skills, which Codex scans from the folder you start it in up to the repository root. There are also /etc/codex/skills for a machine-wide set and system skills that ship with Codex.

How do I call a skill in Codex?

In the Codex CLI or the IDE extension, type $ and the skill's name in your prompt, or run /skills to pick one from the list. Codex can also choose a skill by itself when your request matches the skill's description.

Where do Codex skills go on Windows?

OpenAI gives one path, $HOME/.agents/skills, with no separate Windows path. In PowerShell, $HOME is your user folder (the value of %USERPROFILE%, typically C:\Users\<you>), so the commands on this page work as written. Then check that /skills lists the skill.

Is it ~/.codex/skills or ~/.agents/skills?

OpenAI's docs list .agents/skills, under $HOME and in repositories. The ~/.codex folder holds Codex's settings, config.toml, where you can turn a skill off.