遷移自定義提示到新機制

Custom prompts 已 deprecated。可複用 instructions 推薦使用 skills，因為 skills 可以由 Codex 顯式或隱式呼叫。

flowchart LR
    Old["📜 舊 custom prompt"]
    Q{"用途是什麼？"}
    A["🚀 臨時個人快捷語<br/>（一段固定話術）"]
    B["🛠 穩定工作流<br/>（多步 / 檢查清單 / 模板）"]
    C["📦 團隊分發能力<br/>（要其他人安裝）"]
    Keep["保留為 slash prompt"]
    Skill["遷移到 skill"]
    Plugin["打包到 plugin → skill"]
    Old --> Q
    Q -->|個人 / 單段| A --> Keep
    Q -->|多步 / 含資源| B --> Skill
    Q -->|跨人共享| C --> Plugin

Custom prompts 舊機制可以把 Markdown files 變成 reusable prompts，並在 Codex CLI 和 Codex IDE extension 中作為 slash commands 呼叫。

它有幾個限制：

• 需要顯式 invocation。
• 存在本地 Codex home directory 中，例如 ~/.codex。
• 不會隨 repository 共享。

如果你想分享 prompt，或希望 Codex 根據任務隱式呼叫，請使用 skills。

先判斷遷移到哪裡

舊 custom prompt 不一定都要直接刪除。遷移前先按用途分三類：

如果一個 prompt 只有一段固定話術，例如“幫我總結最後一次 diff”，繼續保留為 slash command 成本最低。

如果它已經包含多步流程、檢查清單、輸入輸出格式、模板或指令碼呼叫，就應該遷移到 skill。官方 skills 機制的定位是 reusable workflows，Codex CLI、IDE extension 和 Codex app 都可以使用。

把舊 prompt 拆成 skill

遷移時不要把整個舊 prompt 原封不動塞進 SKILL.md。更穩的方式是把它拆成四層：

1. 觸發條件：寫進 YAML front matter 的 description，明確什麼時候使用、什麼時候不使用。
2. 執行步驟：寫成 imperative steps，避免“你可以考慮”這類鬆散表述。
3. 資原始檔：模板、長參考、示例輸出放到 references/ 或 assets/。
4. 自動化指令碼：確定性處理邏輯放到 scripts/，由 skill instructions 呼叫。

最小結構如下：

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

SKILL.md 的最小寫法：

---
name: draft-pr-workflow
description: Use when preparing a clean Git branch, commit, and draft pull request from local changes.
---

Follow these steps:

1. Inspect the working tree and identify changed files.
2. Summarize the behavioral change and test coverage.
3. Stage only files relevant to the requested change.
4. Commit with a concise message.
5. Open a draft pull request with summary and verification notes.

遷移後，用一個真實任務觸發它。理想結果是你不需要輸入舊的 /prompts:* 命令，Codex 看到任務描述就能選擇對應 skill；如果 description 太寬，Codex 會誤觸發；如果太窄，則需要每次顯式 $skill-name 呼叫。

建立自定義提示詞

1. 建立 prompts directory：

mkdir -p ~/.codex/prompts

2. 建立 ~/.codex/prompts/draftpr.md，寫入 reusable guidance：

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

为这次工作创建一个名为 `dev/<feature_name>` 的 branch。
如果指定了 files，请先 stage 它们：$FILES。
用清楚的 commit message 提交 staged changes。
在同一 branch 上打开 draft PR。如果提供了 $PR_TITLE，请使用它；否则自己写一个简洁 summary。

3. 重啟 Codex，讓它載入 new prompt。CLI 需要 restart session；如果使用 IDE extension，需要 reload extension。

預期結果：在 slash command menu 中輸入 /prompts:draftpr，會看到這個 custom command。command 下方顯示 front matter 中的 description，並提示 files 和 PR title 是 optional。

新增後設資料和引數

Codex 會在下次 session start 時讀取 prompt metadata，並解析引數標記。

編輯 prompt files 後，重啟 Codex 或開啟 new chat，updates 才會載入。Codex 會忽略 prompts directory 中的 non-Markdown files。

呼叫和管理自定義命令

呼叫方式：

1. 在 Codex，也就是 CLI 或 IDE extension 中，輸入 / 開啟 slash command menu。
2. 輸入 prompts: 或 prompt name，例如 /prompts:draftpr。
3. 提供 required arguments：

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

4. 按 Enter 傳送 expanded instructions。不需要某個 argument 時可以省略。

預期結果：Codex 會展開 draftpr.md 的內容，把引數標記替換成你提供的 arguments，然後把結果作為 message 傳送。

管理方式：編輯或刪除 ~/.codex/prompts/ 下的 files。

Codex 只掃描該 folder 頂層的 Markdown files。因此，每個 custom prompt 都要直接放在 ~/.codex/prompts/ 下，不要放在 subdirectories 中。

遷移後的檢查清單

遷移完成後，按這幾個點驗收：

• Slash command 仍能呼叫：輸入 / 後可以看到舊 prompt，或確認舊 prompt 已經被刪除。
• Skill 能被發現：Codex 啟動時 available skills 列表裡有新 skill，必要時重啟 Codex。
• 觸發邊界清楚：相鄰任務不會誤觸發，新任務也不用複製大段 prompt。
• 專案共享正確：團隊級 workflow 放在 repo .agents/skills，個人 workflow 放在使用者 skills 目錄。
• 大段背景不擠佔上下文：長 reference 放到檔案裡，由 skill 按需讀取。

常見錯誤

• 只把舊 prompt 改名成 SKILL.md，沒有寫清 description。這樣 Codex 很難自動選擇。
• 把所有個人命令都遷移成 skill。一次性話術保留為 custom prompt 更簡單。
• 把團隊 workflow 放進 ~/.codex/prompts/。舊 prompt 不隨 repo 共享，其他人不會自動獲得。
• 刪除舊 prompt 前沒有保留一輪迴退。建議先並行保留一段時間，確認 skill 觸發穩定後再刪。

官方資料

• Agent Skills
• Slash commands in Codex CLI
• Build Codex plugins

接下來去哪