自訂工作流：Skills、自訂 prompt 與 IDE 整合

12.0 一句話 + 一個比喻

這一章的主角是「自訂工作流」——把你重複打的長指令存成可重複使用、甚至可分享的「技能卡」，再讓 Codex 不論在終端機還是編輯器裡都能用上它。

打個比方：

• 自訂 prompt 像是早年的錄音留言：你錄好一段話，按一個鈕就播出去。簡單，但只在你這台機器、而且每次都要你親自按鈕。這個功能已經退役了（下面 12.1 會講為什麼）。
• Skills（技能） 像是一張張技能卡：每張卡寫清楚「這張卡會什麼、什麼時候該拿出來用」。卡片可以跟著專案一起傳給隊友，Codex 還會自己判斷該不該拿出來用。這是現在官方主推的做法。
• IDE 擴充 則是把這位 AI 工程師，從「終端機」這個房間，請進你天天在用的編輯器裡並肩工作。
• Hook（掛鉤） 像是門口的門禁刷卡機：不管來的是誰、心情如何，時間到了就是機械式地跑一次，不靠 Codex 自己判斷要不要動手。

這一章你會學到：

• 為什麼別再投資「自訂 prompt」（以及它的歷史長相）。
• 怎麼寫一張 Skill，讓 Codex 自動或手動取用。
• 怎麼把 Codex 裝進 VS Code / Cursor / JetBrains，而且登入與設定跟 CLI 共用。
• CLI、IDE、桌面 app 三者之間怎麼交接同一份工作。
• 怎麼用 Hook 在關鍵時機自動跑腳本，以及用 Plugin 打包分享、用 /import 把 Claude Code 的設定一次搬過來。

12.1 自訂 prompt 為何被棄用（歷史與相容）

先講一個你可能在舊教學裡看到、但現在別再學的東西：自訂 prompt（custom prompts）。

官方已經正式把它標為「已棄用（deprecated）」。 官方頁面的原文是：

"Custom prompts are deprecated. Use skills for reusable instructions that Codex can invoke explicitly or implicitly."

（自訂 prompt 已棄用。請改用 skills 來做可重用的指令，Codex 可以顯式或隱式地呼叫它們。）

而且不只是「不建議」這麼客氣——從 Codex CLI 0.117.0 起，實際上就壞掉了。社群在 GitHub 上大量回報：升級到 0.117.0 之後，放在 ~/.codex/prompts/ 的自訂 prompt 不再出現在 slash 選單裡，重啟也救不回來。官方把相關 issue 全部以「Closed as not planned（不打算修）」關閉：

那它以前長什麼樣？ 知道一下就好，不必動手（除非你被迫維護一台跑 < 0.117.0 舊版的機器）。

做法是：把一份 Markdown 檔放進 ~/.codex/prompts/，檔名就是指令名。例如 ~/.codex/prompts/draftpr.md 對應指令 draftpr。檔頭可以寫 YAML front matter，支援兩個鍵：

官方的完整範例檔（逐字）長這樣：

---
description: Prep a branch, commit, and open a draft PR
argument-hint: [FILES=<paths>] [PR_TITLE="<title>"]
---

Create a branch named `dev/<feature_name>` for this work.
If files are specified, stage them first: $FILES.
Commit the staged changes with a clear message.
Open a draft PR on the same branch. Use $PR_TITLE when supplied; otherwise write a concise summary yourself.

裡面那些 $FILES、$PR_TITLE 是佔位符（placeholder），呼叫時填入實際值。完整的佔位符規則：

呼叫方式是輸入 / 開選單，打 prompts: 前綴，例（逐字）：

/prompts:draftpr FILES="src/pages/index.astro src/lib/api.ts" PR_TITLE="Add hero animation"

12.2 Skills：可重用、可分享、可自動觸發

Skill（技能）是 Codex 現在主推的「可重用指令」做法。 你可以把它想成一張技能卡：卡面寫清楚「這張卡叫什麼名字、會做什麼」，Codex 平常只瞄一眼卡面，等真的需要時才翻開內頁照做。

它正好補上自訂 prompt 的兩大缺點：

Skill 放哪裡：四個探索層級（入門夠用，完整六層見 12.7）

Codex 會從「最貼近你專案」到「最通用」依序去找 skill：

一個 Skill 的長相

一個 skill 就是一個資料夾，裡面唯一必備的是 SKILL.md，其餘都選配：

my-skill/
├── SKILL.md            （必備）
├── scripts/            （選配：可放輔助腳本）
├── references/         （選配：可放參考文件）
├── assets/             （選配：可放素材）
└── agents/openai.yaml  （選配）

SKILL.md 的檔頭（front matter）必須含兩欄：name（名稱）與 description（描述），接著才是這張卡的指令本文。description 寫得好不好，直接決定 Codex「什麼時候會自動拿出這張卡」——所以要寫清楚「這技能做什麼、適用什麼情境」。

下面是一個示意骨架（把 12.1 那個「開 PR」工作流改寫成 skill 的概念）：

---
name: draft-pr
description: 開一個 dev/<feature> 分支、commit 暫存的改動、開一個草稿 PR。當使用者要把目前的改動整理成 PR 時使用。
---

Create a branch named `dev/<feature_name>` for this work.
If files are specified, stage them first.
Commit the staged changes with a clear message.
Open a draft PR on the same branch with a concise summary.

怎麼叫它出來：顯式 vs 隱式

Skill 有兩種被用到的方式，這是它比自訂 prompt 強的關鍵：

1. 顯式（你親自點名）：在 Codex 內打 /skills 瀏覽並選用，或在 prompt 裡用 $skill-name 的語法 mention 它。
2. 隱式（Codex 自己判斷）：當你交辦的任務，剛好符合某個 skill 的 description 範圍，Codex 會自動把那張卡拿出來照做——你完全不用點名。

為什麼這樣設計省資源：漸進揭露

Skill 用了一招叫 progressive disclosure（漸進揭露）：平常 Codex 只先載入每張卡的 name + description（官方說大約只佔 context 視窗的 2%，或在視窗大小未知時約 8,000 字元），等它決定要用某張卡時，才把那張卡完整的 SKILL.md 讀進來。

白話講：Codex 不會一開始就把所有技能的全文塞進「工作記憶」，而是先看目錄，要用哪張才翻哪張。技能再多，也不會一下子把記憶體塞爆。

12.3 IDE 擴充安裝、登入共用與 slash 指令

學會在終端機自訂工作流之後，我們把場景換到編輯器。好消息：Codex 有官方 IDE 擴充，而且它底層就是同一個 Codex CLI——等於把終端機那位工程師，請進你 VS Code 的側欄。

安裝：先認對「身分證」

支援的編輯器（官方：macOS / Windows / Linux 三平台都可）：

• VS Code 系：Visual Studio Code、VS Code Insiders、Cursor、Windsurf。
• JetBrains 系：Rider、IntelliJ、PyCharm、WebStorm（這是另一套獨立整合，見下方）。

VS Code 系的裝法，任選一種：

1. 從擴充市集搜尋：打開 Extensions 面板，搜尋 Codex（發行者是 OpenAI），按 Install。裝完你會在編輯器側欄看到 Codex。
2. 用深層連結（deep link）直接喚起安裝頁：

VS Code:   vscode:extension/openai.chatgpt
Cursor:    cursor:extension/openai.chatgpt
Windsurf:  windsurf:extension/openai.chatgpt

🪟 Windows 使用者：可以選擇用 Windows sandbox 原生跑 Codex，或在需要 Linux 環境時改用 WSL2（這部分在第 13 章疑難排解會細談）。

JetBrains 系（Rider / IntelliJ / PyCharm / WebStorm）是獨立的整合，不是同一個 VS Code 擴充。它最大的不同是登入方式多一種：除了 ChatGPT 帳號、API key，還可以用 JetBrains AI subscription 登入。VS Code 系沒有這個選項。

除了 VS Code 系與 JetBrains 系，🍎 macOS 開發者另外還有一條路：Xcode 原生整合。JetBrains 系這邊也有個版本眉角值得記一下——它不是一個要你額外去 Marketplace 搜尋安裝的獨立外掛，而是內建在 JetBrains 自家的 AI Assistant 外掛裡（官方口徑約 2026 年 1 月起隨附，最早支援版本是 2025.3）。如果你的 IntelliJ／PyCharm／WebStorm 版本比較舊、打開 AI Assistant 卻找不到 Codex 選項，先檢查 IDE 版本號，不用急著重裝擴充。

不管哪個編輯器，Codex 擴充裡都有三種操作模式可以切換，權限一個比一個寬：

更新方面：擴充預設會自動更新；想手動檢查就在 IDE 內打開擴充頁面。

登入：跟 CLI 共用一份，通常不用再登一次

這是 IDE 與 CLI 交接最關鍵的事實。官方原文：

"The CLI and extension share the same cached login details. If you log out from either one, you'll need to sign in again the next time you start the CLI or extension."

（CLI 與擴充共用同一份快取登入。從任一邊登出，下次開 CLI 或擴充都要重新登入。）

白話翻譯：

• 你已經在終端機 codex login 過了 → 裝好 IDE 擴充，它通常一開就是登入狀態，不用再登一次。
• 反過來也一樣；但任一邊登出，兩邊都要重新登入。

登入用的憑證，存在 ~/.codex/auth.json（或 OS 原生的憑證庫，看你 cli_auth_credentials_store 設定）。第 3 章講過：這個檔形同密碼，別 commit、別貼工單、別貼到聊天室。

含 Codex 的 ChatGPT 方案：Plus / Pro / Business / Edu / Enterprise（方案內含使用額度）；或用有額度的 OpenAI API key 登入。

設定：「行為」走 config.toml，「外觀」走編輯器設定

這是新手最容易卡的地方。記住一句心智模型：

「Agent 行為」走 ~/.codex/config.toml（CLI 與 IDE 共用）；「編輯器外觀/啟動」走編輯器自己的 settings（IDE 專屬）。

官方原文證實：預設 model、approvals、sandbox 這些行為，都寫在共用的 ~/.codex/config.toml，不是寫在編輯器設定裡。所以你想換模型、改核可模式，要去編 config.toml（第 8 章教過），改一次 CLI 與 IDE 同步生效——在編輯器設定面板裡你根本找不到這些鍵。

那編輯器設定管什麼？管「看起來/開起來的樣子」，例如：

IDE 擴充內的 slash 指令（逐字）

在 IDE 擴充的聊天框裡，有自己的一組 slash 指令：

另外兩個是輸入框內的特殊語法（不是 slash 指令）：

• @filename：在 prompt 裡標一個檔案當 context，例「Use @example.tsx as a reference…」。
• $imagegen：用自然語言生成/編輯圖片；官方說明 IDE 內建的圖片生成模型是 gpt-image-2。

常見錯誤與排除法

IDE 擴充目前還在快速迭代，幾個社群回報的常見卡關，遇到時可以先照這個順序排除：

12.4 CLI ↔ IDE ↔ 桌面 app 的交接

最後把「同一份工作怎麼在不同前端之間流動」串起來。記住第 0 章那個比喻：五個前端是同一位員工的五個工作座位，座位之間可以交接。

交接路徑一：CLI ↔ IDE（隱性，靠共用）

CLI 與 IDE 擴充共用同一個 agent、同一份 config.toml、同一份快取登入。所以它們之間的「交接」多半是隱性的，你甚至不用做什麼動作：

• 在 CLI 登入 → IDE 直接可用（反之亦然）。
• 在 config.toml 改 model / approvals / sandbox → CLI 與 IDE 兩邊一致。

換句話說，你不需要某個「把 CLI 內容搬去 IDE」的指令——它們本來就站在同一份地基上。

交接路徑二：本機 ↔ 雲端（/cloud ↔ /local）

在 IDE 擴充裡，你可以把較大的工作丟去 Codex cloud（雲端）跑，然後不離開編輯器就追進度、看結果。官方說明：在 local 與 cloud 之間切換時，會保留對話 context（你的脈絡不會斷）。

操作：設定好一個 cloud environment → /cloud-environment 選它 → /cloud 切到雲端跑；要切回本機就 /local。

交接路徑三：CLI → 桌面 app（/app）

從 0.138.0（2026-06-08）起，Codex CLI 多了一個 /app 指令：

"/app command can now hand off the current CLI thread into Codex Desktop on macOS and native Windows"

（/app 指令現在可以把目前的 CLI 對話 thread，交接到 macOS 與原生 Windows 上的 Codex Desktop。）

也就是：你在終端機聊到一半，想換成桌面 app 的圖形介面繼續——/app 就把這段對話搬過去。

一張圖看懂三條交接路徑

12.5 Hooks：讓 Codex 在關鍵時機自動跑你的腳本

Skill 是一張「Codex 自己判斷要不要拿出來用」的技能卡；Hook（掛鉤）完全不靠 Codex 判斷。把它想成貼在辦公室門口的門禁刷卡機：不管進來的是哪個員工、他當下在想什麼，只要「開門」這個動作發生（也就是某個生命週期事件觸發），刷卡機該跑的邏輯就是機械式地跑一次，沒有「要不要」的空間。這正是 Hook 補上 Skill 空隙的地方——有些事你不想只是「建議」Codex 做，你要它保證發生。

Hook 綁在哪些時機：事件清單

官方定義的生命週期事件，橫跨「一輪對話（turn）」與「一個對話串（thread）」兩種粒度：

設定可以寫在兩個地方，效果相同：獨立的 hooks.json，或直接寫進 config.toml 的 [hooks] 區塊。用 config.toml 寫一條攔截 Bash 工具的 PreToolUse，TOML 語法大概長這樣：

[[hooks.PreToolUse]]
matcher = "^Bash$"
[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

matcher 決定這條 hook 只對哪種工具生效（上例只攔 Bash），command 是實際要跑的程式，timeout 是逾時秒數，statusMessage 是等待時顯示給你看的字。

信任機制、實作走一遍、常見卡關

Hook 不是寫好設定檔就會默默生效。第一次執行「非受管理」的 command hook 之前，Codex 會先擋下來，要求你用 /hooks 手動審閱並「信任」它。信任的判斷基礎是 hook 內容的雜湊值——之後改了那支腳本的路徑或參數，Codex 認得出內容變了，會重新要求信任一次。這個機制本身也是一種結構性護欄：Hook 不會因為你哪天不小心把腳本改壞，就悄悄帶著新內容繼續跑下去。

實際跑一遍最小可行流程，大致是這五步：

1. 建立資料夾放腳本，並把權限設緊一點：mkdir -p ~/.codex/hooks && chmod 700 ~/.codex/hooks。
2. 寫腳本本體，例如 ~/.codex/hooks/log-start.sh：

#!/bin/sh
printf 'SessionStart %s\n' "$(date)" >> "$HOME/.codex/hook-events.log"

3. 寫 ~/.codex/hooks.json，把事件、比對規則（matcher）與要跑的指令接起來：

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          { "type": "command", "command": "~/.codex/hooks/log-start.sh", "timeout": 10 }
        ]
      }
    ]
  }
}

4. 存檔前先跑 python3 -m json.tool ~/.codex/hooks.json 驗一下語法沒寫歪（JSON 對括號、逗號很龜毛，這步能少走不少冤枉路）。
5. 開 codex，打 /hooks 審閱這條新 hook 並按下信任，開一個新的對話串讓它生效，再去看 ~/.codex/hook-events.log 有沒有多一行——這樣才算真的裝好。

想確認自己這版 Codex 支不支援 hooks，可以：

codex features list | grep hooks

12.6 Plugins 與 /import：打包分享、跨工具搬家

Skill、Hook 都是「一個一個裝」的零件。Plugin（外掛）把一整組零件——skills、hooks、MCP server、app connector——打包成一個可以整批安裝、整批升級的單位，適合團隊要在好幾個 repo 之間共用同一套客製化設定的情境。這一節也順便介紹 /import：把你在 Claude Code 那邊已經寫好的設定，整批搬進 Codex CLI 的搬家指令。

Plugin：manifest 長相與安裝／升級指令

一個 plugin 的「身分證」是資料夾根目錄下固定路徑的 .codex-plugin/plugin.json；其餘元件（skills/、hooks/hooks.json、MCP 設定 .mcp.json、app connector 設定 .app.json、assets/）平放在 plugin 根目錄，manifest 只需要宣告它們在哪。最小可用的 manifest：

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable greeting workflow",
  "skills": "./skills/"
}

安裝與管理都是同一組 codex plugin marketplace 系列指令，來源可以是 GitHub repo、npm 套件，也可以是本機路徑：

市集項目的安裝政策分三種狀態：AVAILABLE（可以裝，但預設不裝）、INSTALLED_BY_DEFAULT（新環境會直接幫你裝好）、NOT_AVAILABLE（目前不開放裝）。在 Codex 內打 /plugins 就能瀏覽這些狀態，不用背指令也能操作。

/import：把 Claude Code 的設定與最近對話一次搬進來

如果你是附錄 B那種「兩套 CLI 都在用」的讀者，/import 幫你省掉手動一項項搬的力氣。它只能在 Codex 的互動介面（TUI）裡打，不是可以寫進腳本的 CLI 子指令；跑起來後，畫面會列出三大分組讓你勾選：

畫面預設是全部勾選；第一次請選「Customize selection」，用空白鍵只勾已逐一讀過、確認不含憑證的項目（例如只匯入對話紀錄、不動設定）。MCP、Hooks、Plugins 與 Chat Sessions 都可能帶入外部工具、敏感指示或工作內容；匯入後先在測試環境用 /mcp、/hooks、/plugins 核對，再決定是否啟用。

12.7 🎓 高手進階

前面幾節把「自訂工作流」的骨架都搭起來了：自訂 prompt 退役、Skill 怎麼寫、IDE 怎麼裝、前端怎麼交接、Hook 怎麼在關鍵時機自動跑、Plugin 與 /import 怎麼打包搬家。這一節回頭在 Skill 與 IDE 這兩個你會最常碰的支柱上，往下再挖一層做產品級工作流會碰到的深層細節，最後兩小節（12.7.8、12.7.9）把整章收束成一套心法。本章重「怎麼把格式寫對、把陷阱避開」；更上位的心法層（什麼工作該封成哪一層、為什麼）在第 13 章「高手的工作流」深入——兩章請對照著看。

12.7.1 自訂 prompt：不是「不推薦」，是「叫不出來」——就地搬成 Skill

入門 12.1 說它「已棄用」，口氣其實還太客氣。進階的精準說法是：

在 0.117.0 以後的版本上，自訂 prompt 是「事實死亡」——不是「不建議」，是 slash 選單裡根本叫不出來。 官方把回報的 issue（#15941、#15972）全部 Closed as not planned（不打算修）。

所以這層在新版唯一還值得學的，是「怎麼把舊 prompt 搬成 Skill」。對照配方如下（官方沒有自動搬遷工具，但對應關係明確）：

12.7.2 Skill 探索：六層路徑 + 一條反直覺的撞名規則

入門 12.2 給的是「夠用版」四層。官方文件實際列的是六層，差別在 REPO 範圍其實拆成三列（多了給巢狀 repo 用的兩列）：

最容易踩的雷是撞名規則。官方逐字：

"When skills share names, both appear in selectors — no merging occurs."

（當兩個 skill 同名，兩個都會出現在選單裡——不會合併。）

⚠️ 這跟一般人的直覺相反。多數人以為「就近覆蓋」——專案層的同名 skill 會蓋掉使用者層的。錯。 Codex 不合併、也不覆蓋，而是兩個都列出來讓你自己挑。所以別靠「同名覆蓋」來做版本切換，那個機制不存在；要停用某一個，請用下面 12.7.4 的 skills.config 明確關掉。

12.7.3 agents/openai.yaml：把 Skill 從「一段 prompt」升級成「產品級單元」

入門只說 agents/openai.yaml 是「選配」。其實這支檔才是高手面——它讓一張 Skill 能控制外觀、擋誤觸、自帶外部工具。官方逐字 schema：

interface:
  display_name: "Optional user-facing name"
  short_description: "Optional user-facing description"
  icon_small: "./assets/small-logo.svg"
  icon_large: "./assets/large-logo.png"
  brand_color: "#3B82F6"
  default_prompt: "Optional surrounding prompt to use the skill with"

policy:
  allow_implicit_invocation: false

dependencies:
  tools:
    - type: "mcp"
      value: "openaiDeveloperDocs"
      description: "OpenAI Docs MCP server"
      transport: "streamable_http"
      url: "https://developers.openai.com/mcp"

三個區塊各管一件事：

• interface：純外觀——顯示名、描述、圖示（指向 assets/）、品牌色、外圍 prompt。
• policy.allow_implicit_invocation：這是安全閂（下面 12.7.3-A 細講）。
• dependencies.tools：讓 Skill 自帶 MCP server，安裝時自動接好（下面 12.7.3-B）。

A. allow_implicit_invocation: false 當「危險 skill 的安全閂」

官方逐字：這欄預設是 true（Codex 會依你的 prompt 自己判斷要不要隱式取用）；設成 false 後，Codex 不再自己觸發，只有人類親手打 $skill-name 才會動。

💡 高手用法：凡是部署、migration、rm、寫 production 這類「跑下去會改變外部世界」的 Skill，一律把它設 false。這樣 Codex 不會「自己覺得現在該部署了」就觸發——把破壞性操作從「機器自由心證」降級成「必須人類顯式下令」。這是一道結構性護欄，比在 prompt 裡寫一百句「不要亂部署」可靠得多（這個道理第 13 章會深講）。

B. Skill 自帶 MCP 依賴，安裝即自動接線

dependencies.tools 一旦宣告，Codex 可以自動安裝並接好那個 MCP server，使用者不必手動去編 config.toml 的 [mcp_servers.*]（MCP 設定見第 9 章）。這由 config 旗標 features.skill_mcp_dependency_install（預設開啟）控制；把它關掉就禁止 skill 自動裝 MCP 依賴。

意義：一張 Skill 可以 = 一條含外部工具的完整工作流。例如一個查 OpenAI 文件的 skill，直接把官方 Docs MCP server 的定義帶在身上，別人 clone 你的 repo、用這張 skill，工具自動就位。

12.7.4 三個高手生產力工具：skill-creator、skill-installer、skills.config

別手刻 SKILL.md 從零開始。 Codex 內建兩個工具 skill：

💡 用 $skill-creator 走一遍，好處是它會幫你把 front matter 與 description 措辭寫得符合官方最佳實踐（見下面 12.7.5），不會漏欄。

skills.config——用 config.toml 精準開關 / 載入任意路徑的 skill

config.toml 有個 [skills] 區塊，可以逐張 skill 覆寫設定：

高手用法：① 在 CI 或受限環境用 enabled = false 關掉危險/吵雜的內建 skill；② 用 path 把 skill 放在 monorepo 的共用 tooling 夾再指過去，繞開 .agents/skills 慣例。

12.7.5 description 是工程，不是文案：front-load 觸發詞

隱式選取準不準，全看 description 寫得好不好。官方逐字最佳實踐：

• 「Keep each skill focused on one job.」 一張 skill 只做一件事。
• 「Front-load the key use case and trigger words…」 把「核心用途」和「觸發詞」放在描述句的最前面。

為什麼要前置？因為 Skill 清單受 context 上限約束（入門 12.2 講的 2% / 8,000 字元），當你 skill 數量一多，Codex 會從描述的尾巴開始截短——官方原文甚至說某些 skill 在量大時會被直接省略並給警告。所以觸發詞放句首，就算被截也還在，Codex 才匹配得到。

💡 反面教材：description: 這個技能很有用，可以幫你處理各種跟發布有關的工作流程，包括但不限於……——關鍵詞埋在後面，一截就沒了。正面寫法：description: 部署到 NAS 並做健康檢查。當使用者要把改動上線、發布、deploy 時使用。——用途與觸發詞全在前半句。

12.7.6 把它串起來：一張「確定性部署 skill」的範式

入門說 scripts/ 是「選配」。高手的判準是：凡是「LLM 每次跑可能不一樣、但你要求每次一致」的步驟（跑 lint、產 changelog、跑覆蓋率門檻、部署前健康檢查），就下放到 scripts/ 寫成可執行檔，讓 SKILL.md 只負責「何時呼叫哪支 script、怎麼解讀輸出」。官方定位也是「instruction-only skills are the default；只有需要確定性行為或外部工具時才用 scripts/」。

把本節的零件組起來，一張產品級部署 skill 長這樣：

deploy-check/
├── SKILL.md            # name + description（front-load 觸發詞）
├── agents/openai.yaml  # policy.allow_implicit_invocation: false（危險,不准隱式觸發）
│                       # dependencies.tools 掛部署用的 MCP server
├── scripts/
│   ├── healthcheck.sh  # 確定性:curl -I 驗 Last-Modified、檢查 HTTP 狀態
│   └── rollback.sh
└── references/
    └── runbook.md      # 靠漸進揭露,只在 Codex 判定需要時才載入,不一開始就吃 context

→ 結果：只有人類打 $deploy-check 才會跑（顯式化的安全閂），跑的是確定性 script（不靠 LLM 自由發揮），危險動作不會被隱式誤觸。這就是把「自查」「驗證」從 prompt 的口頭承諾，變成機械事實的做法——背後的心法（為什麼結構比規則可靠）留到第 13 章。

12.7.7 IDE↔CLI 交接的高手細節

入門 12.3、12.4 講了「IDE 擴充底層就是 CLI、登入與 config.toml 共用」。補一個高手會用到的事實：Skills、以及 config.toml 裡所有 agent 行為設定，IDE 擴充跟 CLI 是同一份。

含意：

• 你在 CLI 用 $skill-creator 建好的 skill、放進 $HOME/.agents/skills 的個人技能、改進 config.toml 的 skills.config 開關——打開 IDE 擴充，它們全都在，因為兩邊讀同一份地基。不需要「把 skill 同步到 IDE」這種動作。
• 反過來，你在 config.toml 設的 allow_implicit_invocation（透過 agents/openai.yaml）、features.* 旗標，也對 IDE 內的 Codex 一體生效。

所以「在哪個前端設定 skill」這個問題，答案是：設定一次（在共用的檔案層），CLI 與 IDE 兩邊同步。這正是第 0 章「五個前端是同一位員工的五個座位」在工作流封裝上的具體體現。

12.7.8 Skills 是開放標準：一份 SKILL.md 能不能跨 Codex／Claude Code 通用

還有一個底層事實值得高手知道：Codex CLI 的 Skills 不是 OpenAI 自己關起門發明的格式，它遵循的是一套跟 Claude Code、OpenClaw 等 30 幾種工具共用的「Agent Skills」開放標準。含意是：同一份 SKILL.md，理論上不用改一個字，就能直接放進 Codex CLI 或 Claude Code 的技能資料夾使用——這也是 /import 能夠把 Claude Code 的 skill 幾乎原封不動搬過來的原因。

但「幾乎」兩個字要說清楚：跨工具相容不含權限限制欄位。像 allowed-tools 這種寫在 Claude Code／OpenClaw 裡、用來限制一張 skill 只能呼叫哪些工具的欄位，Codex 讀到時會靜默忽略、不會報錯，但也不會強制執行那個限制。換句話說：

• 在 Claude Code／OpenClaw 寫的 allowed-tools 限制，搬到 Codex 上形同沒寫。
• 反過來，Codex 專屬的 agents/openai.yaml（12.7.3 那個 allow_implicit_invocation 安全閂）也不是開放標準的一部分，Claude Code 不會認得它。

對想維持一套 skill 庫、同時服務兩套 CLI 的團隊，這代表：共用的部分（name／description／指令本文）放心跨工具共用；工具特定的安全閂（Codex 的 agents/openai.yaml、Claude Code 的 allowed-tools）則要各自補一份，不能只寫一邊就當作兩邊都有保護。

12.7.9 五層客製化堆疊：什麼時候該用哪一層

這一章陸續學了 AGENTS.md（第 5 章）、Skill、MCP（第 9 章）、Hook、Plugin，還有其他章節會提到的 Subagent（第 14 章）。零散學完容易腦袋打結：這麼多層，到底什麼工作該封進哪一層？收束成一張選用表：

其中 MCP 與 Skill 的分工特別容易搞混，一句話記住：MCP 是 Codex 能呼叫的工具，Skill 是 Codex 該怎麼用這些工具的操作手冊。一張「去 Jira 找 blocker」的 skill，內文可以直接寫「用 Jira 搜尋工具查詢 blocker」，實際發出查詢呼叫的能力則來自對應的 MCP server——寫 SKILL.md 時不用把 MCP 的實作細節也塞進去，假設工具存在、教它怎麼用就好。

本章小結

這一章你學會了把工作流「打包」與「跨前端搬動」：

• 自訂 prompt 已退役（0.117.0 起失效、官方 Closed as not planned、無 config 開關救回）——新版別投資，知道歷史長相即可。
• Skill 是現在主推的技能卡：放 .agents/skills（隨 repo 分享）或 $HOME/.agents/skills（個人全域）；SKILL.md 必含 name + description；可顯式 /skills / $skill-name 或隱式自動觸發；靠漸進揭露省 context。
• IDE 擴充底層就是 Codex CLI：ID 是 openai.chatgpt、登入與 config.toml 跟 CLI 共用、「行為設定走 config.toml、外觀設定走編輯器」。
• 三條交接路徑：CLI↔IDE 靠共用（隱性）、IDE↔cloud 用 /cloud//local、CLI→Desktop 用 /app。
• Hook 綁在生命週期事件上，不靠 Codex 判斷、時間到了就跑；第一次執行需要 /hooks 手動信任，內容一變就要重新信任。
• Plugin 把 skills/hooks/MCP 打包成可分發單位，codex plugin marketplace 系列指令安裝管理；/import 可以把 Claude Code 的設定與近期對話一次搬進 Codex。

高手進階（12.7）再往下挖一層：

• 舊 prompt 在 0.117.0 後是「叫不出來」，唯一該學的是搬成 Skill 的對照配方；別把舊 $1/KEY=value 展開語法假設成 Skill 內文也吃。
• Skill 探索其實是六層，且同名不覆蓋、是並列（反直覺，別靠它做版本切換）。
• agents/openai.yaml 是產品級關鍵：allow_implicit_invocation: false 當危險 skill 的安全閂（預設 true 要小心）、dependencies.tools 讓 skill 自帶 MCP。
• $skill-creator / $skill-installer / skills.config 三個生產力工具；description 要 front-load 觸發詞（被截也還在）。
• scripts/ = 確定性管線，把「自查/驗證」從口頭承諾變機械事實；心法層在第 13 章。
• Skills 是跨工具開放標準，SKILL.md 格式共通，但 allowed-tools 這類安全性欄位 Codex 不強制執行，別誤以為搬過去照樣有保護。
• 五層客製化堆疊（AGENTS.md → Skill → MCP → Hook → Plugin）：一份寫得好的 AGENTS.md 加兩個目標明確的 skill，勝過拼裝粗糙的五層堆疊，別為了上滿五層而上滿五層。

下一章（也是收尾篇開頭），我們處理出狀況時怎麼辦：codex doctor 健檢、看 log、企業網路與額度管理，並把本章「結構比規則可靠」的心法收束成高手的工作流。

動手試試

1. 在 Codex 內打 /skills，看看官方內建了哪些技能；再到 $HOME/.agents/skills 建一個你自己的資料夾 + SKILL.md（寫好 name 與 description），重新打 /skills 確認它被掃到。
2. 在 VS Code（或 Cursor）的擴充市集搜尋 Codex 裝起來，打開側欄，確認它是不是已經登入（因為跟你 CLI 共用登入）。
3. 在編輯器擴充裡用 @某個檔名 把一個檔案當 context，叫 Codex 解釋它在做什麼，體會「IDE 內參照檔案」跟終端機 @ 引用的差別。
4. （進階）在 Codex 內打 $skill-creator，讓精靈帶你做一張 skill；故意把 description 的觸發詞寫在句尾、再改成寫在句首，觀察 Codex 隱式取用的命中差別。若你寫的是「會改東西」的 skill，試著在 agents/openai.yaml 加 policy.allow_implicit_invocation: false，確認它之後只有你打 $名字 才會動。
5. （進階）在使用者層建一個最簡單的 SessionStart hook（寫一支只會 log 一行字的腳本），走一遍 /hooks 信任流程，開新對話串驗證它真的執行了；接著打 /plugins 看看目前裝了哪些外掛、狀態各是 AVAILABLE／INSTALLED_BY_DEFAULT 哪一種。若你也在用 Claude Code，找個乾淨的測試目錄跑一次 /import，體驗「Customize selection」怎麼挑要匯入的項目。