前言¶

用 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