前言¶

用 Codex 写代码一段时间后，你会发现：系统自带的几个 Skill 不够用，官方精选目录和社区仓库里还有不少现成能力——修 CI、处理 PDF、对接 Linear 等等。问题是，这些 Skill 散落在 GitHub 上，手动克隆、拷贝到本地目录既容易漏步骤，也难知道哪些已经装过。

skill-installer 就是为这件事准备的系统技能：在 Codex 里用 $skill-installer 列出可装列表，或按名称 / 仓库路径把 Skill 装进本地目录。官方文档把它定位为「本地安装精选 Skill」的入口；没有它，发现和安装社区 Skill 会麻烦很多。

这是什么¶

skill-installer 是 OpenAI 维护的 Codex 系统级 Skill，源码在 openai/skills 仓库的 skills/.system/skill-installer 目录下。最新版 Codex 会自动带上 .system 里的 Skill，一般不需要再安装它本身。

一句话定位：把 Skill 安装到 $CODEX_HOME/skills（默认 ~/.codex/skills）。来源默认是官方精选目录 skills/.curated，也可以指定 .experimental，或任意 GitHub 仓库路径（含私有仓库）。

官方描述里写得很清楚：当用户要列出可安装 Skill、安装精选 Skill、或从其他仓库安装时，就该用它。

核心功能与亮点¶

根据官方 SKILL.md 与 Codex 文档，主要能力如下：

1. 列出可安装 Skill
   默认拉取 openai/skills 的 .curated 列表；若问实验性 Skill，可改查 skills/.experimental。列表会标注哪些已经安装。

2. 按名称安装精选 Skill
   在 Codex 中直接 $skill-installer <skill-name>，例如官方示例里的 linear、gh-address-comments。

3. 从任意 GitHub 路径安装
   支持 --repo + --path，或直接给 GitHub 目录 URL；一次可传多个 --path，批量安装。

4. 下载策略
   公有仓库默认直接下载；若遇鉴权 / 权限错误，回退到 git sparse checkout（先 HTTPS，再 SSH）。私有仓库可用本机 git 凭据，或设置 GITHUB_TOKEN / GH_TOKEN。

5. 安装约束清晰
   目标目录已存在则中止，避免覆盖；校验目录内必须有 SKILL.md。安装完成后，官方说明下一轮对话即可使用；若未出现，重启 Codex。

配套脚本在 Skill 目录的 scripts/ 下（需联网，沙箱环境中要申请提权）：

• scripts/list-skills.py：打印可装列表（可加 --format json，或 --path skills/.experimental）
• scripts/install-skill-from-github.py：从 GitHub 安装

常用参数包括：--ref（默认 main）、--dest、--name、--method auto|download|git。

安装与启用¶

skill-installer 属于 .system，随 Codex 预装。官方仓库说明：.system 下的 Skill 已随最新 Codex 自动安装；若用户仍要求「安装」系统 Skill，只需说明这一点；对方坚持时才允许下载覆盖。

在 Codex 中启用方式与其他 Skill 相同：

• 显式调用：输入 $skill-installer，或用 /skills、$ 提及
• 隐式调用：当你说「列出可装 Skill」「帮我装某个 Skill」等，且描述匹配时，Codex 可能自动选用

安装到本地的用户 Skill，默认落在：

$CODEX_HOME/skills/<skill-name>
# 未设置 CODEX_HOME 时 ≈ ~/.codex/skills/<skill-name>

若只想临时禁用某个已装 Skill（不删除文件），可在 ~/.codex/config.toml 里配置：

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

改完后需重启 Codex。

说明：skill-installer 的安装目标是 Codex 的本地 Skill 目录。通用 SKILL.md 格式也可被 Cursor、Claude Code 等工具读取，但本 Skill 的脚本与路径约定是按 Codex 编写的；在其他工具里应使用各自文档中的安装方式，不要默认套用同一套命令。

典型用法示例¶

以下示例均来自 OpenAI 官方文档或仓库 README / SKILL.md。

1. 安装精选 Skill（按名称）

$skill-installer linear

或：

$skill-installer gh-address-comments

2. 安装实验性 Skill

自然语言方式（仓库 README 示例）：

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

或直接给目录 URL：

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

3. 用脚本列出 / 安装（Skill 内部助手脚本）

列出精选（默认）或实验性列表：

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

从指定仓库路径安装：

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

或用 URL：

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

安装成功后，助手应提示用户：下一轮即可使用；若列表里看不到，重启 Codex。

适用场景与注意事项¶

适合：

• 在 Codex 里快速浏览官方 .curated / .experimental 目录
• 把精选或第三方 GitHub 上的 Skill 装到本机做试验
• 需要从私有仓库拉取团队内部 Skill（凭据或 Token 已配置）

注意：

• 目标目录已存在会直接报错中止，不会覆盖；更新前需自行处理旧目录。
• .system Skill（含本安装器）已预装，不必再走一遍安装流程。
• 官方文档写明：$skill-installer 面向本地安装与试验；若要把自己的 Skill 分发给他人复用，更推荐走 plugins 分发。
• openai/skills 仓库 README 目前标注该仓库已 deprecated，并指向 openai/plugins 与「Build plugins」文档作为当前示例入口；同时，Codex Skills 官方文档 仍在说明用 $skill-installer 安装精选 Skill。以一手文档为准，按你的 Codex 版本实际行为操作即可。
• 列表依赖 GitHub API 访问精选目录；不可用时脚本会报错退出。

小结¶

skill-installer 是 Codex Skill 生态里偏「基础设施」的一块：预装在系统层，负责发现精选列表、按名安装、以及从 GitHub（含私有库）拉 Skill 到 ~/.codex/skills。对入门用户来说，记住 $skill-installer 和官方文档里的几个示例，就够把本地 Skill 库搭起来。

官方地址：

• Skill 源码：https://github.com/openai/skills/tree/main/skills/.system/skill-installer
• Codex Skills 文档：https://developers.openai.com/codex/skills