用 Skills 複用能力

Skill 是可複用工作流的編寫格式。它把任務說明、資源和可選指令碼放進一個目錄，讓 Codex 在匹配任務時按同一套方法執行。

如果你反覆複製同一段 prompt，或反覆糾正 Codex 的同一類錯誤，它大機率應該變成 skill。

Skills

檢視 Codex skills 的官方說明。

Create skills

學習如何建立 SKILL.md 和配套資源。

Plugins

當 skill 需要分發給別人安裝時，再打包成 plugin。

Skill 解決什麼

flowchart LR
    Repeat["重複 prompt / 重複糾錯"] --> Skill["Skill"]
    Skill --> Stable["穩定流程"]
    Skill --> Trigger["清楚觸發"]
    Skill --> Verify["固定驗證"]

適合：

文件美化。
PR review。
release note。
日誌分診。
migration planning。
安全檢查清單。
固定格式輸出。

不適合：

一次性任務。
還沒跑穩的流程。
需要大量臨場判斷的開放問題。
只是存放一堆資料的目錄。

基本結構

my-skill/
  SKILL.md
  scripts/
  references/
  assets/

SKILL.md 至少要說明：

skill 名稱。
description：什麼時候觸發，什麼時候不觸發。
輸入。
步驟。
輸出。
驗證方式。
風險邊界。

指令碼、模板和參考資料只在能提升可靠性時加入。不要為了顯得複雜而加檔案。

Codex 如何選擇 skill

Codex 通常先看到 skill 的 name、description 和路徑。只有判斷任務需要時，才載入完整 SKILL.md。

所以 description 必須準確：

開頭寫核心任務。
寫出使用者真實會說的觸發詞。
寫清不適用場景。
避免泛泛寫“提高效率”。

描述越泛，誤觸發越多。

建立流程

推薦順序：

先用普通 prompt 跑通一次。
重複多次，記錄穩定步驟和失敗點。
用 $skill-creator 或手動建立 skill。
用真實任務測試觸發。
修改 description 和驗證步驟。
需要團隊分發時，再做 plugin。

Skill 是流程沉澱，不是流程想象。先實踐，再封裝。

儲存位置和分發

官方 skills 支援 CLI、IDE extension 和 Codex app。儲存位置決定誰能看到它：

範圍	位置	用途
Repo 當前目錄	`$CWD/.agents/skills`	只服務當前工作目錄。
Repo 父目錄	`$CWD/../.agents/skills`	子模組共享同一組技能。
Repo 根目錄	`$REPO_ROOT/.agents/skills`	儲存庫級團隊工作流。
User	`$HOME/.agents/skills`	個人所有專案可用。
Admin	`/etc/codex/skills`	受管理機器統一提供。
System	Codex 內建	OpenAI 打包的通用技能。

Codex 支援 symlinked skill folders。對於大體積技能庫，可以用軟連結複用一份主庫，避免複製多份。

如果要跨 repo、跨團隊分發，或把 skill 與 MCP、app integration 一起打包，使用 plugin。

顯式呼叫和隱式呼叫

Codex 使用 skill 有兩種方式：

顯式呼叫：在 CLI/IDE 中用 /skills 或 $skill-name 指定。
隱式呼叫：Codex 根據任務與 description 的匹配自動選擇。

隱式呼叫依賴 description，所以描述要把觸發詞前置。例如：

---
name: release-note-writer
description: Use when turning merged PRs or git commits into concise release notes. Do not use for general blog writing.
---

這個 description 同時說明“用來寫 release notes”和“不用於普通部落格”。比“幫助寫作”這類泛描述可靠得多。

Progressive disclosure

Skills 的關鍵機制是 progressive disclosure：Codex 啟動時只把 skill name、description 和路徑放進上下文；真正需要時才讀取完整 SKILL.md。

這意味著：

SKILL.md 可以放詳細步驟，但 description 必須短而準。
長參考資料不要塞進 description，放到 references/。
大量 skills 會佔初始上下文預算，描述會被壓縮或省略，所以最重要的觸發詞要寫在開頭。
如果某個技能必須避免誤觸發，可以在 agents/openai.yaml 中關閉 implicit invocation，只允許顯式呼叫。

質量檢查

一個 skill 合格，應滿足：

能被正確觸發。
不會在錯誤任務中誤觸發。
步驟足夠短而明確。
輸出格式穩定。
驗證方式可執行。
不包含金鑰或私有路徑。
修改後能在乾淨任務中複驗。

Skill 的目標是讓 Codex 少問重複問題、少犯重複錯誤、按穩定標準交付。