---
title: "遷移自定義提示到新機制"
description: "說明 custom prompts 棄用後，如何把可複用 instructions 遷移到 Codex skills。"
verifiedAt: "2026-05-07"
---

> [!NOTE]
> **這一篇用 8 分鐘換什麼**：把"custom prompts → skills"的遷移從一次性替換重新理解成**按用途三分類**——臨時個人話術留為 prompt，穩定工作流升級為 skill，團隊分發能力打包成 plugin。讀完後你不會一刀切刪除舊 prompt，也不會把所有東西都遷成 skill。

Custom prompts 已 deprecated。可複用 instructions 推薦使用 [skills](https://developers.openai.com/codex/skills)，因為 skills 可以由 Codex 顯式或隱式呼叫。

```mermaid
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](https://developers.openai.com/codex/skills)。

## 先判斷遷移到哪裡

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

| 型別 | 推薦去向 | 判斷標準 |
| --- | --- | --- |
| 臨時個人快捷語 | 繼續保留為 prompt | 只給自己用，只需要 slash command 顯式觸發，不需要隨專案共享。 |
| 穩定工作流 | 遷移到 skill | 需要 Codex 根據任務自動識別，或需要附帶 scripts、references、assets。 |
| 團隊分發能力 | 遷移到 plugin 中的 skill | 希望其他開發者安裝，或要把 skill 和 app/MCP 配置一起打包。 |

如果一個 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 呼叫。

最小結構如下：

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

`SKILL.md` 的最小寫法：

```markdown
---
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：

```bash
mkdir -p ~/.codex/prompts
```

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

```markdown
---
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，並解析引數標記。

| 欄位/佔位 | 說明 |
| --- | --- |
| **Description** | 在 popup 的 command name 下顯示。用 YAML front matter 中的 `description:` 設定。 |
| **Argument hint** | 用 `argument-hint: KEY=<value>` 說明預期 parameters。 |
| **Positional 引數標記** | `$1` 到 `$9` 會從 command 後的 space-separated arguments 展開。`$ARGUMENTS` 包含全部 positional arguments。 |
| **Named 引數標記** | 使用 `$FILE` 或 `$TICKET_ID` 這類 uppercase names，並透過 `KEY=value` 傳值。有空格的值要 quote，例如 `FOCUS="loading state"`。 |
| **Literal dollar signs** | 寫 `$$` 可以在 expanded prompt 中輸出單個 `$`。 |

編輯 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：

```text
/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](https://developers.openai.com/codex/skills)
- [Slash commands in Codex CLI](https://developers.openai.com/codex/cli/slash-commands)
- [Build Codex plugins](https://developers.openai.com/codex/plugins/build)

## 接下來去哪

<Cards>
  <Card title="Skills 複用" href="/zh-Hant/docs/codex/official/03-extensions/09-skills-reuse" description="遷過去之後怎麼寫好一個 skill" />
  <Card title="構建 Plugins" href="/zh-Hant/docs/codex/official/03-extensions/69-build-plugins" description="團隊分發用的 plugin 打包流程" />
  <Card title="Plugins 管理" href="/zh-Hant/docs/codex/official/03-extensions/68-plugins-manage" description="安裝 / 升級 / 移除 plugin" />
  <Card title="CLI Slash 命令" href="/zh-Hant/docs/codex/official/01-products/25-cli-slash" description="保留下來的舊 prompt 仍走這裡" />
  <Card title="自定義行為" href="/zh-Hant/docs/codex/official/02-config-security/48-customize-behavior" description="把 skill / prompt 與配置統一編排" />
</Cards>
