01 · 技能與外掛程式

兩個概念，一句話分清

• 技能（Skill）：一項具體任務或工作流所需的指令和配套資源，打包在一起。
• 外掛程式（Plugin）：可安裝的套件，可以包含技能、連接器，或者兩者都有。 連接器由 MCP 伺服器提供支援，也可以帶自定義的 ChatGPT 介面。

先用技能把流程本身設計出來；需要分發給別人，再打包成外掛程式。

什麼時候該寫技能

判斷標準很實在：這件事你已經用同樣的方式做過三次以上，而且每次都要重新交代一遍。

比如每週的釋出說明、程式碼審查時那幾條固定檢查、把某類日誌整理成排查報告、 按團隊規範寫 commit message。技能記錄的是「你目前處理這類工作的方式」， 讓 Codex 每次遇到都走同一套流程。

不適合寫成技能的：一次性的活、每次要求都不一樣的活、 以及那些其實該寫進 AGENTS.md 的全域性約定。

技能長什麼樣

一個包含 SKILL.md 的目錄，可以再放指令碼和參考資料。SKILL.md 必須有 name 和 description：

---
name: release-notes
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for ChatGPT or Codex to follow.

description 這一行比正文更重要——它決定了這個技能什麼時候會被自動選中。 寫「生成釋出說明」不如寫「當用戶要求根據兩個 git tag 之間的提交生成面向使用者的釋出說明時使用； 不要用於內部變更日誌」。

它怎麼決定用不用某個技能

技能採用漸進式披露：ChatGPT 和 Codex 先只拿到每項技能的名稱和描述， 決定要用了才載入完整的 SKILL.md。

在 Codex 裡，這個初始列表還包含每項技能的檔案路徑。 為了不擠佔提示裡的其他內容，列表最多佔模型上下文視窗的 2%； 上下文視窗大小未知時最多 8000 個字元。裝的技能太多，Codex 會先壓縮描述， 再多就直接省略一部分並給出警告。

所以：技能不是裝得越多越好。裝了三十個用不上的，代價是你真正需要的那個可能被擠掉。

兩種觸發方式：

• 顯式：ChatGPT 裡輸入 @ 選，Codex CLI / IDE 裡跑 /skills 或輸入 $ 引用。
• 隱式：任務和技能的 description 對上了，它自己選。

三種做法

一、讓它幫你寫。 在 Codex 裡：

$skill-creator

建立器會問你這個技能幹什麼、什麼時候觸發、只要指令還是也要指令碼（預設只有指令）。

二、演示給它看。 流程複雜到不好描述的時候，用錄製與重放： 錄一遍你的操作，它檢查各步驟，據此起草一個可複用的技能。

三、手寫。 建目錄、寫 SKILL.md，就上面那個格式。 Codex 會自動檢測技能變更；沒顯示出來就重啟。

Codex 從哪裡載入技能

這張表值得記住，因為它決定了「這個技能對誰生效」：

範圍	位置	適合放什麼
REPO	$CWD/.agents/skills	只跟當前這個微服務 / 模組有關的技能
REPO	$CWD/../.agents/skills	巢狀目錄結構裡，共享區域的技能
REPO	$REPO_ROOT/.agents/skills	整個倉庫通用，提交進版本庫，所有人都能用
USER	$HOME/.agents/skills	你個人的，跨所有倉庫
ADMIN	/etc/codex/skills	機器 / 容器級共享，適合 SDK 指令碼和自動化
SYSTEM	OpenAI 隨 Codex 捆綁	skill-creator、plan 這類內建技能

對於倉庫範圍，Codex 從當前工作目錄一路向上遍歷到倉庫根，掃描各級的 .agents/skills。 同名技能不會合並，兩個都會出現在選擇器裡——所以命名別撞車。

技能資料夾支援符號連結，掃描時會跟隨。

想臨時關掉某個技能而不刪它：

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

裝別人寫好的技能

$skill-installer linear

也可以讓安裝器從其他倉庫下載。這條路適合本地折騰和試驗； 要分發自己的技能，官方建議優先用外掛程式。

什麼時候該上外掛程式

技能資料夾解決的是「我和我的倉庫」；外掛程式解決的是「別人怎麼裝上我這套東西」。

需要外掛程式的訊號：

• 要把兩個以上技能捆一起發
• 技能要連外部服務（GitHub、Google Drive、Slack……），得帶連接器
• 想讓網頁版和移動端的 ChatGPT 也能用——獨立技能只能在桌面應用、Codex CLI 和 IDE 擴充功能裡用， 外掛程式裡捆的技能才能在網頁版、桌面端和移動端的聊天與 Work 裡用

ChatGPT 和 Codex 共用同一個外掛程式目錄，所以裝一次兩邊都能用。

一條實踐建議

技能最容易犯的錯是寫太大。「程式碼審查技能」這種範圍的東西，最後會變成一篇沒人讀的長文件， 它也不知道什麼時候該用。

拆小：「檢查 SQL 注入風險」「檢查錯誤處理是否吞異常」「檢查新增依賴的許可證」—— 每個技能一件事，描述寫清楚觸發條件。它會自己在合適的時候挑合適的那個。

相關官方文件

• 技能與外掛程式
• 構建技能
• 錄製與重放
• 外掛程式 · 構建外掛程式