Codex Skills 怎麼用：安裝目錄、$ 調用、skill-installer 與 config.toml 停用

本文根據 OpenAI 官方文檔《Build skills》整理，資料核對於 2026-10-11。ChatGPT 網頁和桌面 App 裏的技能入口見《ChatGPT Skills 怎麼用》，本文只講 Codex CLI 和 IDE 擴展。Codex 還沒裝好的話先看《Codex 入門》。

適用於誰

• 搜「codex skills 怎麼用」「codex skills 安裝」「codex skills 配置」「codex 如何觸發 skill」的人；
• 從 Claude Code 轉過來，想把已有的 Skill 搬到 Codex 裏的人；
• 照舊教學把技能放進 ~/.codex/skills 卻不確定對不對的人。

結論先說

1. Codex 掃描的目錄是 .agents/skills：項目裏從當前目錄一路向上到倉庫根，每一層的 .agents/skills 都會被掃描；個人級是 $HOME/.agents/skills。
2. 兩種調用方式：顯式調用，運行 /skills 或者輸入 $ 選擇技能；隱式調用，任務和技能的 description 對得上時 Codex 自己選用。
3. 不用手寫也能有：$skill-creator 幫你創建，$skill-installer 幫你安裝現成的。
4. 格式就是開放標準的 SKILL.md，從別的工具搬過來的技能文件夾，放對目錄即可。
5. 想停用不想刪：在 ~/.codex/config.toml 裏加一條 [[skills.config]]，把 enabled 設為 false。

一、技能放在哪

官方表格列出的掃描位置：

幾條官方說明：

• 同名技能不會合並，兩個都可能出現在技能選擇器裏。所以不要在個人目錄和倉庫裏各放一份同名的；
• Codex 會跟隨符號連結指向的技能文件夾；
• Codex 會自動發現變化；更新沒有出現時，重啟 Codex。

每個技能是一個文件夾，結構如下，只有 SKILL.md 是必需的：

my-skill/
├── SKILL.md           # 必需，frontmatter 裏有 name 和 description
├── scripts/           # 可選，可執行代碼
├── references/        # 可選，文檔
├── assets/            # 可選，模板和資源
└── agents/openai.yaml # 可選，外觀與依賴

二、怎麼調用

顯式調用：在 Codex CLI 或 IDE 擴展裏運行 /skills，或者在輸入框裏輸入 $，從列表裏選技能。明確知道要用哪個時用這種方式最穩。

隱式調用：不點名，Codex 根據任務和各技能 description 的匹配程度自行決定。

關於上下文佔用，官方的說明是：Codex 一開始只加載每個技能的名稱、描述和文件路徑，決定使用某個技能時才讀取完整的 SKILL.md。這份初始清單最多佔上下文窗口的 2%（窗口大小未知時按 8,000 字符）；技能裝得很多時，Codex 會先縮短描述，仍放不下時可能略去部分技能並給出警告。

這意味着兩件事：description 要把關鍵的使用場景寫在最前面；用不上的技能及時停用。

三、創建技能

三種方式：

1. 用內置的創建器：在 Codex 裏調用 $skill-creator，按提示描述你要的技能。官方說明預設生成的是隻含說明、不帶腳本的技能；
2. 手寫：新建一個文件夾，裏面放 SKILL.md，frontmatter 寫 name 和 description，後面接操作說明。寫法見《SKILL.md 怎麼寫》；
3. 錄製並回放：把一次操作錄下來，由錄製器起草成技能。這是 ChatGPT 桌面 App 的功能，詳見上面的 ChatGPT Skills 教學。

官方給的幾條寫作建議：

• 一個技能只做一件事；
• 能用文字說明就不用腳本，除非需要確定性的行為或外部工具；
• 步驟用祈使句，寫明輸入和輸出；
• 拿幾句真實的提問去試，確認描述能正確觸發。

四、安裝現成的技能

用內置的安裝器：

text
$skill-installer linear

這是官方文檔裏的例子，安裝名為 linear 的技能。官方還說明可以讓安裝器從其他倉庫下載技能。新裝的技能會被自動發現，沒出現就重啟 Codex。

也可以手動安裝：把技能文件夾複製到 $HOME/.agents/skills（個人）或倉庫的 .agents/skills（項目）下。

如果是要把自己的技能分發給別人，官方推薦的途徑是做成插件。技能是編寫格式，插件是分發方式；插件裏的技能還能在 ChatGPT 的網頁、桌面和手機端使用，而單獨的技能文件夾只在 ChatGPT 桌面 App、Codex CLI 和 IDE 擴展裏可用。

安裝第三方技能之前，先把 SKILL.md 和 scripts/ 裏的文件讀一遍，見《Skill 安全嗎：安裝前檢查什麼》。

五、停用某個技能

不想刪除、只想暫時關掉，在 ~/.codex/config.toml 裏加一段，path 指向那個技能的 SKILL.md：

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

改完配置後重啟 Codex。

六、agents/openai.yaml 是幹什麼的

這是 Codex 在開放標準之外加的可選文件，放在技能文件夾的 agents/ 目錄下，有三部分：

有副作用的技能（部署、發消息、改線上數據），把 allow_implicit_invocation 設為 false，只在你點名時才運行。

常見問題

Q：~/.codex/skills 還能用嗎？

官方文檔現在寫的用戶級目錄是 $HOME/.agents/skills，表格裏沒有 ~/.codex/skills。新建技能按文檔裏的路徑放。

Q：Claude Code 的技能能直接用嗎？

兩邊都基於同一份開放規範，SKILL.md 的基本格式通用，把技能文件夾複製到 .agents/skills 即可。但 Claude Code 專有的 frontmatter 字段（如 context: fork）在 Codex 裏沒有對應的作用，依賴這些字段的技能需要調整。

Q：技能不觸發怎麼辦？

先用 $ 顯式調用，確認技能本身正常；再回頭改 description。思路見《Skill 不觸發怎麼辦》。

Q：Codex 的技能和 MCP 是什麼關係？

MCP 負責把 Codex 連到外部服務，技能負責說明怎麼做事；技能可以在 agents/openai.yaml 裏聲明自己依賴哪個 MCP 伺服器。MCP 的配置見《Codex 怎麼配置 MCP》。

參考資料

• Build skills（OpenAI 官方文檔）：https://learn.chatgpt.com/docs/build-skills
• Specification（Agent Skills 官方規範）：https://agentskills.io/specification