How to Install Codex Skills

Codex has no codex skills install subcommand. Installing a skill means one of three things, and they don't all put the file in the same place — which is the single most common reason a freshly installed skill doesn't show up.

The three ways to add a skill

Route	Use when	Lands in
`$skill-installer <name>`	Pulling from OpenAI's catalog	`~/.codex/skills/<name>`
`$skill-installer` with a repo path or URL	Pulling from any GitHub repository	`~/.codex/skills/<name>` unless you pass `--dest`
Writing the file yourself	Your own skills, or committing skills to a repo	Wherever you put it — use `.agents/skills`

All three are covered below. If a skill isn't appearing afterwards, jump to which directory did it go in.

Install from the curated catalog

skill-installer is a skill that ships with Codex, so there's nothing to set up. Invoke it with no arguments to see what's available:

$skill-installer

Or install one directly by name:

$skill-installer gh-fix-ci

By default it reads OpenAI's curated catalog at openai/skills. That repository is now deprecated — its README opens by directing people to openai/plugins instead. The repo is still public and the installer still points at it (observed 16 August 2026), so this works today; treat it as a path with a stated end-of-life rather than the long-term answer. The best Codex skills covers what's in the catalog and how the migration affects it.

One thing to ignore: both the catalog's README and the bundled installer still describe installing from an .experimental folder. That folder now returns a 404. Commands referencing it will fail.

Install from any GitHub repo

The installer isn't limited to OpenAI's catalog. Give it a repo and a path, or a GitHub URL:

$skill-installer install the mcp-builder skill from ComposioHQ/awesome-codex-skills

Under the hood it runs a bundled Python helper you can also reason about directly. From the installer's own SKILL.md:

scripts/install-skill-from-github.py --repo <owner>/<repo> --path <path/to/skill>
scripts/install-skill-from-github.py --url https://github.com/<owner>/<repo>/tree/<ref>/<path>

The documented options:

Flag	Effect
`--repo` / `--path`	Source repo and skill directory. `--path` is repeatable to install several at once
`--url`	A GitHub tree URL instead of repo + path
`--ref <ref>`	Branch or tag. Defaults to `main`
`--dest <path>`	Install somewhere other than the default destination
`--method auto\|download\|git`	Force direct download or git sparse checkout
`--name`	Override the installed skill's name (defaults to the path basename)

Behavior worth knowing before you run it: it defaults to direct download for public repos and falls back to git sparse checkout if it hits an auth or permission error. Private repos work through your existing git credentials, or a GITHUB_TOKEN / GH_TOKEN. It aborts if the destination directory already exists rather than overwriting — so reinstalling means removing the old copy first.

Because these scripts reach the network, Codex will ask to escalate sandbox permissions when it runs them.

Write the file yourself

For your own skills, or for skills you want committed alongside a codebase, skip the installer. A skill is just a directory with a SKILL.md in it.

Personal, available in every project:

mkdir -p ~/.agents/skills/my-skill

Project-scoped, committed to the repo so your team gets it:

mkdir -p .agents/skills/my-skill

Then write SKILL.md with at minimum a name and a description. How to create a Codex skill covers writing one that actually triggers.

Codex scans .agents/skills in every directory between your project root and your working directory, so a skill committed at the repo root applies throughout the repo, and a package can carry its own.

Which directory did it go in

The two locations behave differently, and this trips people up constantly:

~/.agents/skills — the current user-level location, and what the official documentation lists.
~/.codex/skills — where $skill-installer writes. The Codex source marks this as the deprecated user skills location, "kept for backward compatibility."

Both are scanned, so both work. But it means an installed skill and one you wrote by hand can sit in different directories on the same machine, and a guide that mentions only one of them will send you looking in the wrong place. The flagship guide has the full scope table and the source reference.

After installing anything, restart Codex. The official docs say to restart after changes, and the installer tells you a new skill will be available "on their next turn." Some third-party guides claim restarts are no longer necessary — that contradicts both first-party sources as of August 2026.

Turning a skill off

You don't have to delete a skill to stop it loading. Add an entry to ~/.codex/config.toml:

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

Restart Codex afterwards.

Troubleshooting

Symptom	Likely cause
Installed skill doesn't appear	You didn't restart Codex, or you're looking in `.agents/skills` for something the installer put in `~/.codex/skills`
Hand-written skill doesn't appear	Wrong filename (must be exactly `SKILL.md`), invalid YAML frontmatter, or a directory outside the scanned chain
Install aborts immediately	The destination directory already exists — remove it or pass `--dest`
Install fails on a private repo	Authenticate git, or set `GITHUB_TOKEN` / `GH_TOKEN`
A command referencing `.experimental` fails	That folder was removed from the catalog repo; the docs referencing it are stale
Skill loads but never triggers on its own	The `description` doesn't match how you phrase the task — see creating a skill

Sources

Codex — Build skills (official docs)
openai/codex — bundled skill-installer SKILL.md — destination, flags, and fallback behavior
openai/codex — codex-rs/ext/skills/src/host_roots.rs — which directories are scanned
openai/skills — the catalog, and its deprecation notice