How to install skills in Codex: every method, step by step

Pick a scope first

Every install method ends the same way: a folder containing SKILL.md lands in a directory Codex scans. The only real decision is which directory.

Scope	Path	Who gets it
Personal	~/.agents/skills/<name>/	You, in every repository
Project	<repo>/.agents/skills/<name>/	Everyone who clones the repo, once you commit it
Machine	/etc/codex/skills/<name>/	Every user on that machine or container

Codex scans .agents/skills in the current directory and every parent up to the repository root, so a project skill can also live in a subfolder of a monorepo and apply only there. Older Codex releases used ~/.codex/skills; current releases still read it for backward compatibility, but ~/.agents/skills is the documented location.

Use personal scope for skills about how you work (debugging, commit style, prompting habits). Use project scope for skills about the codebase (its release process, its migration rules, its API conventions). The team sharing guide goes deeper on the project route.

Method 1: the one-line installer

codexskills.dev publishes a small POSIX shell script that downloads skills from this catalog and unpacks them. The site is independent and not affiliated with OpenAI; read the script at https://codexskills.dev/install.sh before piping it to a shell if you prefer.

# one skill, personal scope (~/.agents/skills)
curl -fsSL https://codexskills.dev/install.sh | sh -s -- systematic-debugging

# several at once
curl -fsSL https://codexskills.dev/install.sh | sh -s -- code-review git-commit-hygiene pull-request-writing

# into the current repository (./.agents/skills)
curl -fsSL https://codexskills.dev/install.sh | sh -s -- --project agents-md-authoring

# every skill in a category
curl -fsSL https://codexskills.dev/install.sh | sh -s -- --category security

# search the catalog without installing
curl -fsSL https://codexskills.dev/install.sh | sh -s -- --list pdf

Option	Effect
--project	Install into ./.agents/skills
--dir <path>	Install into any directory you choose
--legacy	Install into $CODEX_HOME/skills (~/.codex/skills) for older Codex releases
--category <name>	Add every skill in a category
--list [query]	Print available skills, optionally filtered

Each skill unpacks to <skills-dir>/<name>/. If that folder already exists, the installer replaces it, so re-running the command is also how you update.

The script needs curl or wget, plus unzip or python3.

Method 2: the interactive picker

If you would rather search and tick boxes, the same catalog ships as a single-file Node.js CLI. It is not published to npm, so download it and run it with Node 20.12 or newer:

curl -fsSL https://codexskills.dev/cli.mjs -o codex-skills.mjs
node codex-skills.mjs

With no arguments it opens a search box with multi-select. It also takes commands for scripting:

node codex-skills.mjs install systematic-debugging test-driven-development
node codex-skills.mjs list react
node codex-skills.mjs install --project --category testing --all
node codex-skills.mjs installed          # what you installed from this catalog
node codex-skills.mjs update             # re-download all of them
node codex-skills.mjs remove pdf-forms

--project, --dir <path> and --legacy choose the target directory the same way as the shell installer; --json gives machine-readable output for list and installed.

Method 3: Windows PowerShell

On Windows, download install.ps1 and run it with the skill names:

irm https://codexskills.dev/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1 systematic-debugging code-review

It accepts -Project, -Dir <path>, -Category <name>, -List [query] and -Legacy, and installs to $HOME\.agents\skills by default. The Node CLI from method 2 also works on Windows.

Method 4: download a zip and copy it

Every skill page links a zip, and the files are served from predictable URLs:

curl -fsSLO https://codexskills.dev/downloads/systematic-debugging.zip
mkdir -p ~/.agents/skills
unzip -o systematic-debugging.zip -d ~/.agents/skills

Each zip contains one folder named after the skill, holding SKILL.md, any references/ or scripts/ it uses, and a generated agents/openai.yaml that gives Codex a display name, a short description and a starter prompt. Bundles exist too: /downloads/category/<category>.zip and /downloads/collection/<slug>.zip, for example the Starter Pack.

Copying by hand works for any skill from any source. The rule is simply that SKILL.md must sit one level inside the skills directory: ~/.agents/skills/systematic-debugging/SKILL.md, not ~/.agents/skills/SKILL.md and not ~/.agents/skills/systematic-debugging/systematic-debugging/SKILL.md.

Method 5: git clone and symlink

If you keep skills in a git repository, your own or a team’s, clone it once and symlink the folders you want. Codex follows symlinks when it scans skill directories.

git clone https://github.com/your-org/agent-skills ~/src/agent-skills
mkdir -p ~/.agents/skills
ln -s ~/src/agent-skills/skills/release-notes ~/.agents/skills/release-notes

Updating becomes git -C ~/src/agent-skills pull. This is the cleanest setup when you also edit the skills, because your changes are tracked and easy to share.

Method 6: $skill-installer inside Codex

Codex ships a built-in skill for installing skills. Mention it in a session:

$skill-installer linear

By name it installs from OpenAI’s curated list. You can also ask it to install from a GitHub repository path, for example “install the skill at github.com/your-org/agent-skills/tree/main/skills/release-notes”. It downloads over the network, so expect an approval prompt if your sandbox blocks network access. Note that OpenAI now points to plugins as the main way to distribute reusable skills; $skill-installer is meant for local setup and experiments.

Method 7: plugins

Plugins are the packaged form of skills, often bundled with MCP servers. In the CLI, run /plugins to browse marketplaces, install a plugin, and toggle it on or off. Bundled skills become available when you start a new session. The IDE extension does not support plugins; use the CLI or the ChatGPT desktop app. The plugins guide explains marketplaces and when a plugin is the better choice.

Verify the install

1. Start Codex in a repository: codex.
2. Run /skills and look for the skill in the list, or type $ and the first letters of its name.
3. Try it explicitly: $systematic-debugging the login test fails intermittently.
4. Try it implicitly with a request that matches its description, without the $ mention.

If step 2 fails, check the path (ls ~/.agents/skills/<name>/SKILL.md), make sure the frontmatter starts on the first line with ---, and restart Codex. If step 4 fails but step 3 works, the skill is installed and the issue is matching; see why a skill is not triggering.

Update a skill

• Installed with the shell script, PowerShell or a zip: run the same install command again. The skill folder is replaced.
• Installed with the Node CLI: node codex-skills.mjs update.
• Symlinked from git: git pull in the source repository.
• Project skills: update them in a pull request like any other code, so reviewers see the change.

Codex notices changed files on its own; restart if the new version does not take effect.

Remove or disable a skill

To remove a skill, delete its folder:

rm -rf ~/.agents/skills/pdf-forms

To keep the files but stop Codex from using the skill, disable it in ~/.codex/config.toml, then restart Codex:

[[skills.config]]
path = "/Users/you/.agents/skills/pdf-forms/SKILL.md"
enabled = false

Disabling is handy for a project skill you do not want in your own sessions, since deleting it would show up as a change in the repository.

Before you install third-party skills

A skill is instructions plus, sometimes, scripts that Codex may run on your machine. Read SKILL.md and anything in scripts/ before installing a skill from a source you do not know. Codex’s sandbox and approval prompts still apply to every command a skill triggers, but reading first is cheaper than reviewing a surprise. The skill safety guide has a short checklist.