進階 prompt 工程與指示檔案心法

前面章節教你把守則檔案寫出來、把外部工具接上去；這一章教你把這整套系統用到骨子裡——指示檔案該分幾層放、@ 引用哪些檔案吃得下、怎麼把重複工作封裝成隨選載入的 Skill 或一支獨立子代理，還有官方自己怎麼教你寫 prompt。

想像你已經請了這位新同事一段時間：他讀得懂你放在抽屜裡的守則手冊、也接得上你交代的外部工具。現在你想要的，是把「怎麼交辦」這件事做得更細——手冊該分幾本放在哪裡才不會互相打架、想把一段常做的流程直接寫成他隨選就能拿出來用的「作業標準書」、甚至想乾脆培養一位專才助理，只做某一件事、不會亂碰別的。這一章就是教你這些「用到骨子裡」的細節。

這一章你會學到：

• 「舊的 gh copilot 跟現在教的 copilot，到底哪裡不一樣？」——開篇先把這個容易認錯的陷阱釐清一次。
• 「使用者層、儲存庫層、路徑限定、跨工具相容……到底有幾種指示檔案？」——一張完整的六路徑地圖。
• 「我可以在指示檔裡用 @ 拉別的檔案進來嗎？」——哪些檔案支援、哪些不支援，一次講清楚。
• 「同一段流程做第三次了，能不能讓它自己記住怎麼做？」——SKILL.md 怎麼寫、放哪裡。
• 「想養一個只做 code review、絕對不動手改檔案的專才助理，怎麼設定？」——.agent.md 完整欄位表。
• 「官方自己怎麼教人寫 prompt？」——拆解成可以直接照做的心法清單，外加 /refine 這個新指令。

13.1 先分清楚：舊 gh copilot 與新 GitHub Copilot CLI

在往下講指示檔案之前，有一件事要先講清楚，否則你查到的資料可能整篇都對不上號：GitHub 把「在終端機用 Copilot」這件事，前後推出過兩個完全不同的東西。

(料源：official，GitHub Blog changelog，2025-09-25、2026-02-25 GA 公告)

新舊怎麼一眼分辨：指令開頭打的是 gh copilot ... 還是單獨一個 copilot ...，這是最快的判斷法——前者是舊擴充功能的呼叫方式，後者才是本書從頭到尾在教的獨立產品。想更完整認識這兩者的差異，第 0 章有更詳細的拆解。

另外要提醒一件事，免得你把它誤認成第三個新產品：2026-06-23 官方發布過一則「Copilot CLI 新終端介面 GA」的公告，這不是另一個新工具，是同一個 copilot 指令的終端介面重新設計（分頁瀏覽、引導式設定流程、主題感知色彩），不是版本重新編號，也跟本章要講的指示檔案機制無關。

(料源：official，2026-06-23 changelog)

13.2 完整指示檔案家族：六條路徑一次看懂

前面章節你已經寫過 copilot-instructions.md，也知道它會讀 AGENTS.md／CLAUDE.md／GEMINI.md。這一節把完整的檔案家族攤開成一張表，包含前面沒細講的兩塊：使用者層的模組化指示，以及用環境變數擴充搜尋範圍這條路。

(料源：official，Add custom instructions for Copilot CLI)

六條路徑聽起來很多，但拆開看只有兩個維度：誰寫的（Copilot CLI 自家格式 vs 別人家的開放標準）和範圍多大（跨所有專案的使用者層 vs 單一 repo 的儲存庫層）。模組化那兩種（*.instructions.md）比較特別，靠 frontmatter 的 applyTo 欄位限定「只在碰到符合的檔案路徑時才載入」，適合放「只有前端目錄才用得到」這類局部規則，不會被平白無故塞進每一次對話。

去哪裡找：標準位置探索機制

知道有哪些檔名還不夠，Copilot CLI 還得知道去哪些資料夾找。官方原文：

"Copilot CLI discovers repository and agent instruction files in the standard locations: the repository root, the current working directory, intermediate directories between them, and any directories nested in the path of a file it is working on."

翻成白話，探索範圍是四塊拼起來：儲存庫根目錄、你目前所在的工作目錄、根目錄到你目前位置之間沿途所有中繼資料夾，外加它正在處理的那個檔案所在路徑上任何巢狀資料夾。

(料源：official，同上文件「Where Copilot CLI looks for custom instructions」段落)

合併不分先後——跟 Codex CLI 的規則正好相反

這一條規則本站 Copilot 單元第 5 章已經完整展開過，這裡只重申結論，避免你把心智模型帶錯棚：

"When multiple applicable user-level and repository instruction files exist, Copilot CLI combines their instructions. It removes duplicate copies of identical user-level copilot-instructions.md, repository-wide, and agent instructions, but does not define a general precedence order between these files. Avoid conflicting instructions."

翻成一句話：多份指示檔全部合併、完全相同的內容會去重，但誰蓋過誰——官方明講不定義，請你自己避免寫出互相矛盾的規則。 這跟 Codex CLI「近者覆寫遠者」的明確規則正好相反，是四方對照裡張力最大的一組差異，詳細比較請見第 5 章。

(料源：official，同上文件「How multiple instruction files interact」段落)

兩個個人層級的環境變數

除了指示檔案本身，還有兩個環境變數可以改變 Copilot CLI 去哪裡找設定：

• COPILOT_CUSTOM_INSTRUCTIONS_DIRS：設定後，Copilot CLI 會額外去搜尋這個環境變數指定的目錄找指示檔案，適合企業把共用守則放在受控路徑，或個人想要一個「跨所有專案都收錄」的自訂資料夾，不必全部塞進 $HOME/.copilot/。
• COPILOT_HOME：設了就整個改用該目錄取代預設的 $HOME/.copilot，等於幫這次執行換一整套「人格」——包含指示檔、設定檔、記憶全部一起搬家。這個變數影響的範圍比指示檔案大得多，第 8 章有更完整的介紹。

(料源：official)

13.3 @ 引用其他檔案：哪些吃得下、哪些不支援

前面章節你學過在指示檔裡用 @ 加相對路徑引用其他檔案，這裡補一個容易忽略的細節：不是每一種指示檔案都支援 @ 引用。

(料源：official)

@../shared/team-conventions.md

支援的三種檔案裡，Copilot CLI 會立即讀取被引用的檔案，而且支援「被引用的檔案裡面又引用別的檔案」——也就是遞迴引用。限制跟第 5 章教過的一樣：只能寫相對路徑，不接受絕對路徑或 ~/ 開頭的路徑。

13.4 SKILL.md：把重複工作封裝成隨選載入的能力

指示檔案是「每次都會被讀進去」的被動背景知識；Skill 是「按需才載入」的可複用能力——你不用每次都在 prompt 裡重講一次同一套流程該怎麼做，把它寫成一個 skill，Copilot CLI 需要時才去載入，平常不佔 context 額度。

路徑慣例：

(料源：official，Add skills for Copilot CLI)

每個 skill 是一個子目錄，內含一份 SKILL.md（YAML frontmatter 必填 name、description 兩個欄位），加上選填的 scripts/（要跑的腳本）、references/（參考資料，需要時才讀）、assets/（素材檔）子目錄。以下是一份示意寫法（不是官方逐字範例，只是示範結構）：

---
name: release-notes
description: 產生本次發布的更新摘要。使用者要求「幫我整理這次的更新內容」或「寫一份 changelog」時觸發。
---

# Release Notes 生成技能

1. 讀取 git log 自上次 tag 以來的所有 commit。
2. 依 conventional commit 前綴分類（feat / fix / docs …）。
3. 輸出成 Markdown 條列，附上對應 commit hash。

(料源：practice，欄位規格為官方逐字，具體內容為示意寫法)

13.5 .agent.md：把一種角色封裝成可重複呼叫的子代理

指示檔案管的是「這個專案永遠適用的規矩」，Skill 管的是「按需拿出來用的具體流程」；.agent.md 更進一步，封裝的是一整個「角色」——例如一位只讀不改、專門做安全審查的專才助理，或一位只負責寫測試、不碰其他程式碼的助理。

路徑與優先序：

• 專案層：.github/agents/
• 使用者層：~/.copilot/agents/
• 優先順序：使用者層（home）優先於專案層

(料源：official，Custom agents configuration reference)

frontmatter 完整欄位表

(料源：official，同上文件)

Body（frontmatter 以下的 Markdown 內容，寫 agent 的行為／專業領域／指令）最長 30,000 字元。一份只讀不改、專做安全審查的示意範例：

---
description: 專門負責 code review，只讀不改，聚焦在安全性與邊界條件檢查。
name: security-reviewer
target: github-copilot
tools: ["read", "search"]
disable-model-invocation: false
user-invocable: true
---

你是一位資深安全審查員。收到程式碼改動時，優先檢查：
1. 輸入驗證與邊界條件
2. 是否有敏感資訊外洩風險
3. 權限檢查是否完整

只指出問題並說明理由，不要直接動手修改任何檔案。

(料源：practice，欄位規格為官方逐字，具體內容為示意寫法)

建立方式：讓它自動生成，或自己手動填

不想從零手刻 YAML frontmatter，互動模式打 /agent 選「Create new agent」，可以讓 Copilot 依你口頭描述自動生成一份完整的 agent profile，生成後給你 Continue（採用）／Review content（先看內容）／Try again（重來）／Quit（放棄）四個選項；也可以選手動填三欄（名稱、描述、指示）自己寫。

/agent

(料源：official)

13.6 官方 Prompt Engineering 心法

指示檔案、Skill、Custom Agent 都是「常駐或按需的背景知識」；這一節回到最基本的單位——這一次的 prompt 該怎麼寫。官方 Prompt Engineering 文件與 CLI Best Practices 頁整理出幾條可以直接照做的心法：

(料源：official，Prompt engineering、CLI best practices)

/refine：把一句籠統的話先精煉再送出

1.0.71 新增的指令，作用是把你隨口打的一句粗略 prompt，先精煉成更清楚的版本，再實際送出執行：

/refine

(料源：official)

13.7 Plan 模式：先讓它想清楚，再讓它動手

Plan 模式的完整操作方式（跟 standard／autopilot 之間怎麼切換、官方安全警語）第 7 章已經整章講過，這裡只從「prompt 工程」的角度補一句話：為什麼官方建議先進 Plan 模式，而不是直接讓它動手。

按 Shift+Tab 循環切換進入 Plan 模式，Copilot 會先分析你的請求、可能反問釐清問題、產出一份實作計畫——這個階段不寫程式碼。官方在 2026-01-21 的功能公告裡把這個設計定位成「先想清楚、再邊做邊調整」：

(料源：official，Plan before you build, steer as you go)

這跟 Codex CLI 的 /plan 精神一致，都是「先分離設計與實作，擋住做著做著就跑題」的思路，但機制上有一個不同：Codex CLI 用獨立的 /plan 指令，也支援 Shift+Tab 循環；Copilot CLI 則是用同一個 Shift+Tab 快捷鍵，在互動模式的多個模式（一般模式 → Plan → Autopilot 等）之間循環切換，沒有另外的單獨指令。

本章小結

這一章你把 Copilot CLI 的可複用機制用到更深一層：開篇先分清楚舊 gh copilot 跟新獨立 copilot 指令，避免查到過時資料走錯棚；接著把六種指示檔案路徑攤成一張完整地圖，重申「合併不分先後」這條跟 Codex CLI 相反的規則，並補上模組化指示「不含中繼資料夾」的探索例外；然後學會哪些檔案支援 @ 引用（copilot-instructions.md／AGENTS.md／CLAUDE.md）、哪些不支援（GEMINI.md／.instructions.md）。可複用能力這塊，你認識了 SKILL.md（按需載入的具體技能）與 .agent.md（封裝成角色的子代理，含完整 frontmatter 欄位表），也知道使用者層 agent 設定會贏過專案層——跟指示檔案「不定義優先順序」正好是不同的規則。最後整理了官方 prompt engineering 心法、/refine 這個新指令，以及 Plan 模式在「先想清楚再動手」這件事上的角色。

動手試試

1. 在你自己一個常用的專案裡，建一個 .agents/skills/ 或 .claude/skills/ 資料夾，仿照 13.4 節的範例寫一個最小的 SKILL.md（只填 name 跟 description 兩個必填欄位），開 copilot 試著用一句符合 description 描述的話，看它會不會自動載入這個 skill。
2. 打 /agent，選「Create new agent」，用口頭描述讓 Copilot 幫你自動生成一份 .agent.md（例如「一個只負責寫測試、不改其他程式碼的助理」），看它生出來的 frontmatter 跟 13.5 節的欄位表對不對得上。
3. 在你的 AGENTS.md 裡故意寫一段 @ 引用其他檔案，再在一份 GEMINI.md 裡也寫一段一模一樣的引用語法，實機比對哪個生效、哪個沒反應——親自驗證 13.3 節的支援矩陣。
4. 按 Shift+Tab 切進 Plan 模式，丟一個稍微複雜、模糊的任務進去，看它反問你哪些澄清問題；同一個任務再直接用一般模式跑一次，比較兩種跑法產出的差異。
5. 用 /refine 把一句你臨時想到、講得很籠統的 prompt 精煉一次，看看它幫你補了哪些細節，再決定要不要送出。

本章官方文件參考

• 自訂指示檔案：https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions
• Skills：https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills
• Custom agents 設定參考：https://docs.github.com/en/copilot/reference/custom-agents-configuration
• Prompt engineering：https://docs.github.com/en/copilot/concepts/prompting/prompt-engineering
• CLI best practices：https://docs.github.com/en/copilot/how-tos/copilot-cli/cli-best-practices
• Plan mode 功能公告：https://github.blog/changelog/2026-01-21-github-copilot-cli-plan-before-you-build-steer-as-you-go/
• 舊擴充功能棄用公告：https://github.blog/changelog/2025-09-25-upcoming-deprecation-of-gh-copilot-cli-extension/
• GA 公告：https://github.blog/changelog/2026-02-25-github-copilot-cli-is-now-generally-available/