Preface¶

After using Codex for a while, you will find that the few built-in system Skills are not enough, and there are many ready-made capabilities in the official curated directory and community repositories—fixing CI, processing PDFs, integrating with Linear, and so on. The problem is that these Skills are scattered across GitHub, and manually cloning and copying them to the local directory is prone to missing steps, and it is also difficult to keep track of which ones have already been installed.

skill-installer is the system Skill built for this exact purpose: in Codex, use $skill-installer to list available Skills, or install Skills to your local directory by name or repository path. The official documentation positions it as the entry point for “installing curated Skills locally”; without it, discovering and installing community Skills will be much more troublesome.

What it is¶

skill-installer is an system-level Skill for Codex maintained by OpenAI, with its source code located in the skills/.system/skill-installer directory of the openai/skills repository. The latest version of Codex will automatically include the Skills under .system, so you generally do not need to install it yourself.

In one sentence: it installs Skills to $CODEX_HOME/skills (default is ~/.codex/skills). The default source is the official curated directory skills/.curated, but you can also specify .experimental, or any GitHub repository path (including private repositories).

The official description makes it clear: this is the tool to use when you want to list installable Skills, install curated Skills, or install from other repositories.

Core Features and Highlights¶

Based on the official SKILL.md and Codex documentation, its main capabilities are as follows:

List Installable Skills
By default, it pulls the list from the .curated directory of openai/skills; if you ask about experimental Skills, you can check skills/.experimental instead. The list will mark which Skills have already been installed.
Install Curated Skills by Name
Directly run $skill-installer <skill-name> in Codex, such as linear and gh-address-comments from the official examples.
Install from Any GitHub Path
Supports using --repo + --path, or directly providing a GitHub directory URL; you can pass multiple --path parameters at once for batch installation.
Download Strategy
Public repositories are downloaded directly by default; if authentication/permission errors occur, it will fall back to git sparse checkout (HTTPS first, then SSH). Private repositories can use local git credentials, or set the GITHUB_TOKEN / GH_TOKEN environment variable.
Clear Installation Constraints
It will abort if the target directory already exists to avoid overwriting; it verifies that the directory must contain a SKILL.md file. After installation, the official instructions state that you can use the Skill in the next conversation; if it does not appear, restart Codex.

The supporting scripts are located in the scripts/ directory under the Skill directory (requires internet access, and you need to request elevated privileges in a sandbox environment):
- scripts/list-skills.py: Prints the list of installable Skills (add --format json, or --path skills/.experimental to specify the path)
- scripts/install-skill-from-github.py: Installs a Skill from GitHub

Common parameters include: --ref (default main), --dest, --name, --method auto|download|git.

Installation and Activation¶

skill-installer belongs to .system and is pre-installed with Codex. The official repository notes: Skills under .system are automatically installed with the latest Codex; if a user still asks to “install” a system Skill, you only need to explain this; only allow overwriting by downloading if they insist.

The way to activate it in Codex is the same as other Skills:
- Explicit invocation: Enter $skill-installer, or mention it with /skills or $
- Implicit invocation: When you say “list available Skills”, “help me install a certain Skill”, etc., and the description matches, Codex may automatically select this Skill

User-installed Skills will by default be placed in:

$CODEX_HOME/skills/<skill-name>
# ≈ ~/.codex/skills/<skill-name> if CODEX_HOME is not set

If you only want to temporarily disable an installed Skill (without deleting the file), you can configure it in ~/.codex/config.toml:

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

You need to restart Codex after making changes.

Note: The installation target of skill-installer is Codex’s local Skill directory. The universal SKILL.md format can also be read by tools like Cursor, Claude Code, etc., but this Skill’s scripts and path conventions are written for Codex; in other tools, you should use their respective documented installation methods, and do not default to applying the same commands.

Typical Usage Examples¶

The following examples are all from OpenAI’s official documentation or the repository’s README / SKILL.md.

1. Install Curated Skills (by Name)

$skill-installer linear

Or:

$skill-installer gh-address-comments

2. Install Experimental Skills
In natural language (from the repository README example):

$skill-installer install the create-plan skill from the .experimental folder

Or directly provide the directory URL:

$skill-installer install https://github.com/openai/skills/tree/main/skills/.experimental/create-plan

3. Use the Scripts to List / Install (Internal Helper Scripts for the Skill)
List the curated (default) or experimental list:

scripts/list-skills.py
scripts/list-skills.py --format json
scripts/list-skills.py --path skills/.experimental

Install from a specified repository path:

scripts/install-skill-from-github.py --repo openai/skills --path skills/.experimental/create-plan

Or use a URL:

scripts/install-skill-from-github.py --url https://github.com/openai/skills/tree/main/skills/.experimental/create-plan

After a successful installation, the assistant should prompt the user: you can use the Skill in the next conversation; if it does not appear in the list, restart Codex.

Applicable Scenarios and Notes¶

For these scenarios:
- Quickly browse the official .curated / .experimental directories within Codex
- Install curated or third-party GitHub Skills to your local machine for testing
- Need to pull internal team Skills from private repositories (with credentials or Token configured)

Notes:
- It will directly throw an error and abort if the target directory already exists, and will not overwrite it; you need to handle the old directory yourself before updating.
- .system Skills (including this installer) are pre-installed, so you do not need to go through the installation process again.
- The official documentation states that $skill-installer is intended for local installation and testing; if you want to distribute your own Skills for others to reuse, it is more recommended to use plugins for distribution.
- The openai/skills repository README currently marks the repository as deprecated, and points to openai/plugins and the “Build plugins” documentation as the current entry point for examples; at the same time, the Codex Skills official documentation still mentions using $skill-installer to install curated Skills. Please refer to the official documentation and follow the actual behavior of your Codex version.
- The list depends on GitHub API access to the curated directory; the script will throw an error and exit if it is unavailable.

Summary¶

skill-installer is a piece of “infrastructure” in the Codex Skill ecosystem: pre-installed at the system layer, it is responsible for discovering the curated list, installing Skills by name, and pulling Skills from GitHub (including private repositories) to ~/.codex/skills. For beginner users, remembering $skill-installer and a few examples from the official documentation is enough to set up your local Skill library.

Official links:
- Skill source code: https://github.com/openai/skills/tree/main/skills/.system/skill-installer
- Codex Skills documentation: https://developers.openai.com/codex/skills

# skill-installer: The "Package Manager" for Installing Skills on Codex