重複 Prompt 可以整理成固定工作流程

同一個專案準備拉取請求（Pull Request, PR）時，開發者會反覆交代 Codex：比較哪個分支、讀取哪些規則、摘要包含哪些欄位、測試沒有執行時如何標示。

每次重新撰寫提示詞（Prompt），內容容易漏項，團隊成員也可能輸出不同格式。

技能（Skill）可以把這類重複工作封裝成一組可重用指示。它是一個包含 SKILL.md 的目錄，可依需要加入參考資料、腳本與範本。

Codex 先看到 Skill 的名稱與描述，任務符合描述時，才讀取完整指示與相關檔案，再依其中定義的流程工作。

今天會把「產生 PR 摘要」整理成專案 Skill。使用者提出產生摘要的需求，或明確指定 $pr-summary 時，Codex 就能採用固定的輸入來源、摘要格式、風險欄位與測試欄位。

Skill 負責流程與格式，實際差異（Diff）、測試結果及專案規則仍從當次儲存庫取得。

Skill、AGENTS.md 與單次提示詞各有範圍

AGENTS.md 適合記錄專案長期有效的共同規則，例如可修改目錄、測試命令、命名方式與禁止事項。單次提示詞描述目前任務，例如這次要摘要哪個分支、基準分支是什麼，以及是否已有人工驗證結果。Skill 則保存一項工作會反覆使用的步驟與交付格式。

以拉取請求（Pull Request, PR）摘要為例，「禁止讀取 .env」屬於專案規則，「比較 origin/main...HEAD」是這次任務的輸入，「輸出摘要、主要變更、風險、測試與審查提醒」適合放進 Skill。三種內容分開後，專案政策更新、工作流程調整與單次需求變動都能在對應位置處理。

Skill 不必複製整份 AGENTS.md，也不應把某一次 PR 的檔名與結論寫死。過度重複會讓規則分散，日後修改其中一份時容易出現衝突。

Skill 可以要求 Codex 先讀取適用的 AGENTS.md，再將當次使用者指示與實際 Git 證據帶入流程。

一個 Skill 由觸發描述、指示與資源組成

每個 Skill 都有自己的目錄，並以 SKILL.md 作為必要入口。檔案開頭是 YAML front matter，其中 name 是 Skill 名稱，description 說明它能完成什麼工作，以及哪些情境應考慮使用。

詳細步驟放在 SKILL.md 正文。內容應交代預期輸入、執行順序、交付格式、禁止推測的資料，以及缺少資訊時要詢問或停止的條件。

描述寫得太寬，Skill 會在相鄰任務中被誤用；描述過於含糊，Codex 可能無法在合適時機選到它。

篇幅較長的政策與範例可以放進 references/，可直接套用的文件放進 assets/，需要穩定計算或檔案處理時才加入 scripts/。

今天我們只需要讀取 Git 資料並產生文字摘要，因此採用 SKILL.md 加一份輸出範本，讓結構先維持單純。

.codex/
└── skills/
    └── pr-summary/
        ├── SKILL.md
        └── assets/
            └── pr-summary-template.md

放在 .codex/skills/ 的 Skill 只服務目前儲存庫，適合和團隊共同維護。個人跨專案使用的 Skill 可以放在 ~/.codex/skills/。

PR 摘要需要引用專案規則與 Git 慣例，因此會使用專案範圍。

先固定 PR 摘要需要的輸入與證據

這個 Skill 接收基準分支作為主要輸入，例如 origin/main。使用者已指定基準分支時，Codex 直接採用；使用者沒有指定時，先檢查儲存庫的預設遠端分支。

仍無法確認時，要詢問使用者，不能自行假設 main、master 或其他名稱。

摘要內容應來自可查證的 Git 資料。Codex 需要讀取適用的 AGENTS.md，接著檢查工作目錄狀態、提交範圍、Diff 統計、完整 Diff 與相關測試結果。未提交變更若包含在摘要範圍內，必須明確標示，避免讀者以為內容都已存在於目前分支的 Commit。

測試欄位只能記錄有證據的結果。Codex 可以引用這次工作階段實際執行的命令與輸出，也可以引用使用者提供的結果。找不到證據時寫「未執行」及原因。風險同樣要連回具體檔案、行為或缺少的驗證，不能只用「低風險」帶過。

撰寫 pr-summary 的 SKILL.md

建立 .codex/skills/pr-summary/SKILL.md。description 同時寫出工作內容與觸發情境，讓 Codex 能辨識「產生 PR 摘要」、「整理合併說明」等需求。

正文則固定資料來源、處理步驟、輸出格式與停止條件。

---
name: pr-summary
description: Generate a review-ready pull request summary from a Git diff when the user asks for a PR description, merge summary, or change summary.
---

Use this skill to prepare a PR summary from repository evidence.

## Inputs

- Use the base ref provided by the user.
- If no base ref is provided, inspect the repository default branch.
- If the base ref still cannot be confirmed, ask the user before continuing.

## Evidence

1. Read the applicable `AGENTS.md` files.
2. Run `git status --short`.
3. Inspect `git log --oneline <base>..HEAD`.
4. Inspect `git diff --stat <base>...HEAD` and `git diff <base>...HEAD`.
5. Use test results from this session or results supplied by the user.

Do not read secrets, modify files, create commits, push branches, or access the
network. Do not claim that a test passed without command output or user-provided
evidence.

## Output

Load `assets/pr-summary-template.md` and complete every section.

- Connect each main change to files or behavior visible in the diff.
- Describe risks with their conditions and affected behavior.
- Record each test command and result. Write `未執行` with the reason when no
  result is available.
- Put unresolved assumptions and missing evidence in review notes.

Keep the summary concise. Do not invent issue numbers, deployment status,
performance results, compatibility claims, or reviewer approval.

## Stop conditions

Stop and report the missing evidence when the base ref does not exist, the diff
cannot be read, repository rules are unavailable, or the requested range is
ambiguous.

這份 Skill 採用唯讀 Git 命令，沒有要求 Codex 修改程式、建立 Commit 或推送分支。

團隊若允許摘要包含工作目錄中的未提交內容，需要另外寫明讀取方式與標示規則。沒有這項約定時，範例以基準分支到 HEAD 的差異為主要範圍，再由 git status --short 提醒尚未納入的變更。

用資產檔固定交付格式

接著建立 .codex/skills/pr-summary/assets/pr-summary-template.md。範本負責固定標題與欄位，SKILL.md 負責說明如何取得和判斷內容。

日後團隊調整 PR 格式時，只需更新範本與相關指示，不必要求每位成員各自保存一段提示詞。

## 摘要

用 2～4 句說明這次修改解決的問題與結果。

## 主要變更

- 說明可由 Diff 驗證的行為變更，並附相關檔案。

## 風險與影響

- 說明觸發條件、受影響行為及尚待確認的風險。
- 沒有發現具體風險時，寫明已檢查的範圍與限制。

## 測試

- `命令`：通過、失敗或未執行，並附簡短原因。

## Review 提醒

- 列出需要人工確認的設計、相容性、資料或部署事項。

範本中的文字是填寫要求，輸出時應替換成實際內容。主要變更不應只是檔名清單，還要交代行為如何改變。

風險與 Review 提醒有不同用途：前者描述出錯條件與影響，後者指出審查者應核對的證據或決策。

測試欄位保留命令、狀態與原因，可以減少「已測試」這類模糊說法。若只執行單元測試，摘要應如實記錄。Lint、整合測試或 Build 沒有執行時仍要保留欄位，讓審查者知道驗證缺口。

用實際 Diff 測試 Skill

Skill 完成後，先選擇一個差異範圍清楚的分支。確認基準分支存在，並自行查看 git status 與 Diff 統計，掌握 Codex 應讀到的內容。

接著可用 $pr-summary 明確觸發，讓第一次測試能判斷 Skill 是否成功載入。

使用 $pr-summary，為目前分支相對於 origin/main 的變更產生 PR 摘要。
只讀取儲存庫與現有測試證據，不要修改檔案、建立 Commit 或推送遠端。

收到摘要後，逐項回到 Diff 核對。摘要列出的每項主要變更都應找得到檔案與行為證據，風險要有觸發條件，測試狀態要和命令輸出一致，沒有證據的項目應出現在 Review 提醒。

輸出格式正確仍不代表內容正確，人工檢查不能省略。

第一輪通過後，再測試三種情境：使用一般語句要求整理 PR 說明、故意省略基準分支，以及提出相鄰但不需要此 Skill 的任務。

前兩種可以驗證觸發與補問行為，第三種用來確認 Skill 不會過度啟動。也可以使用 /skills 查看可用 Skill，再從清單中選擇它進行測試。

Skill 的修改也需要版本審查

Skill 會影響 Codex 讀取哪些資料、執行哪些命令及如何回報結果，因此它應和程式碼一樣接受 Review。

修改 description 時，要重新測試應觸發與不應觸發的請求。修改工作步驟時，要確認權限與命令範圍。修改範本時，要檢查原有欄位是否仍能提供審查所需證據。

團隊的 PR 規範、測試命令或風險欄位改變後，Skill 也要一起更新。若產生的摘要常需要人工補上同一項資料，可以先確認該資料是否穩定、能否從儲存庫取得，再調整輸入或範本。單一任務才會出現的細節，留在當次提示詞即可。

外部取得的 Skill 應先閱讀 SKILL.md、腳本與資產，再決定是否使用。腳本可能讀取檔案、呼叫網路或修改工作區，Skill 內的文字也可能要求超出預期的行動。

使用最小權限測試，保留 Git 檢查點，並核對實際命令與輸出，才能讓重用流程維持可理解、可審查與可調整。

參考資料：

• Build skills