How to install a skill in Codex CLI

Requires Node.js 18 or newer, which you already have if Codex CLI is installed. The --agent codex flag writes into Codex's own folder; -y accepts the defaults. Take the owner, repository and skill name from the skill's page on this site.

To browse a whole repository, drop the @skill part: npx skills add obra/superpowers --agent codex opens a picker listing every skill it contains.

npx skills add obra/superpowers@systematic-debugging --agent codex -y

With -g the skill goes to ~/.codex/skills/<name>/ and applies to every directory you run codex in. Without -g it goes to .agents/skills/<name>/ in the current repository. Codex searches upward from the working directory, so a project skill is found from any subfolder of the repository.

Codex also reads the shared ~/.agents/skills/ location, so a skill installed without --agent may still work. The dedicated folder is more predictable when you run several agents on one machine and want different skill sets in each.

npx skills add obra/superpowers@systematic-debugging --agent codex -g -y

# Global:  ~/.codex/skills/systematic-debugging/SKILL.md
# Project: .agents/skills/systematic-debugging/SKILL.md

Codex reads skill folders when a session starts. If codex is already running, start a new session (the /new command, or quit and relaunch). Then type /skills to list what was discovered, with each skill's description. A skill that is missing from that list was not found on disk or has invalid frontmatter.

If Codex says /skills is not a command, your build predates skill support. Update with npm install -g @openai/codex@latest and try again.

codex
/skills

Codex loads a skill automatically when your request matches its description. To call one explicitly, mention it with a dollar sign anywhere in the prompt: $systematic-debugging then the request. Explicit calls are the reliable way to use skills whose description is empty or vague, and a good way to learn what a new skill does.

AGENTS.md is not a skill. Codex reads AGENTS.md on every turn as standing instructions; a skill is read only when needed. Keep AGENTS.md short and move long procedures into skills so they do not cost tokens on every message.

$systematic-debugging the login test fails only on CI, find out why before changing anything

Codex runs commands inside a sandbox that, by default, blocks network access and limits writes to the working directory. A skill that only contains Markdown is unaffected. A skill whose instructions fetch a URL at run time, or whose scripts install packages, will fail quietly under the default policy. Check the skill page for the scripts indicator before installing, and if you trust the skill, run codex with a less restrictive sandbox for that session.

Never loosen the sandbox for a skill you have not read. Skills execute with your permissions; the sandbox is the one thing standing between an instruction file and your machine.

npx skills update refreshes every skill the CLI installed. To remove one, delete its folder from ~/.codex/skills/ or the project's .agents/skills/ and start a new session. Codex has no registry of its own; the folder is the whole record.

npx skills update

Not in /skills after installing. Start a new session first; Codex does not rescan mid-session. If it is still missing, open the folder and confirm SKILL.md exists at the top level with name and description in the frontmatter. A skill nested one folder deeper is not found.

The CLI prints No valid skills found. The repository's SKILL.md lacks frontmatter or the author moved the skill. Follow the repository link on the skill page for the current path, or copy the folder into .agents/skills/ by hand.

Listed but never used. Codex matches the request against the description text. Rephrase to match, or use the $name form. Two skills with the same name in different folders hide each other; rename one.

Windows: run the install from PowerShell or Git Bash with Node.js on the PATH. Global installs may create symlinks, which need Developer Mode enabled; if you see a permission error, turn it on in Settings or run the command once as administrator.