當談到 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 時，開發者往往會執著於格式——搞定 YAML、建好目錄結構、遵循規範。但現在已經有超過 30 種 Agent 工具（像是 Claude Code、Gemini CLI 和 Cursor）採用相同的佈局，格式問題基本上已經是過去式了。
真正的挑戰在於內容設計。規範文件告訴你如何打包一個技能，但完全沒教你如何組織內部的邏輯。舉例來說，一個包裝了 FastAPI 慣例的技能，其運作方式與一個四步驟的文件管線完全不同，即使它們的 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 檔案從外部看起來一模一樣。
透過研究整個生態系中技能如何被建構——從 Anthropic 的倉庫、Vercel 到 Google 的內部指南——我們發現了五種反覆出現的設計模式，能幫助開發者打造更強大的 Agent。
作者：@Saboo_Shubham_ 和 @lavinigam
本文將搭配實際可運作的 ADK 程式碼，逐一介紹每一種模式：
- Tool Wrapper（工具包裝器）：讓你的 Agent 瞬間成為任何函式庫的專家
- Generator（生成器）：從可重複使用的模板產出結構化文件
- Reviewer（審查員）：根據檢查清單按嚴重程度為程式碼評分
- Inversion（反向模式）：Agent 在行動前先訪問你
- Pipeline（管線）：透過檢查點強制執行嚴格的逐步工作流程
模式 1：Tool Wrapper（工具包裝器）
Tool Wrapper 能為你的 Agent 提供特定函式庫的即時上下文。你無需將 API 慣例硬編碼到系統提示中，而是將它們打包成一個技能。你的 Agent 只有在實際處理該技術時才會載入這個上下文。
這是最容易實作的模式。𝕊𝕂𝕀𝕃𝕃.𝕞𝕕 檔案會監聽使用者提示中特定的函式庫關鍵字，動態地從 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ 目錄載入你的內部文件，並將這些規則視為絕對真理來應用。這個機制正是你用於將團隊內部編碼指南或特定框架的最佳實踐，直接分發到開發者工作流程中的方法。
以下是一個 Tool Wrapper 的範例，它教導 Agent 如何撰寫 FastAPI 程式碼。請注意，指令明確告訴 Agent 只有在開始審查或撰寫程式碼時才載入 𝚌𝚘𝚗𝚟𝚎𝚗𝚝𝚒𝚘𝚗𝚜.𝚖𝚍 檔案：
1# skills/api-expert/SKILL.md2---3name: api-expert4description: FastAPI 開發最佳實踐與慣例。在建立、審查或除錯 FastAPI 應用程式、REST API 或 Pydantic 模型時使用。5metadata:6 pattern: tool-wrapper7 domain: fastapi8---910你是 FastAPI 開發的專家。將這些慣例應用於使用者的程式碼或問題。1112## 核心慣例1314載入 'references/conventions.md' 以獲取完整的 FastAPI 最佳實踐清單。1516## 審查程式碼時171. 載入慣例參考文件182. 將使用者的程式碼與每一條慣例進行比對193. 對於每個違規，引用具體規則並建議修正方法2021## 撰寫程式碼時221. 載入慣例參考文件232. 嚴格遵循每一條慣例243. 為所有函式簽名添加型別註解254. 使用 Annotated 風格進行依賴注入
模式 2：Generator（生成器）
Tool Wrapper 應用知識，而 Generator 則強制產生一致的輸出。如果你苦於 Agent 每次執行時都會生成不同結構的文件，Generator 可以透過編排「填空」流程來解決這個問題。
它利用兩個可選目錄：𝚊𝚜𝚜𝚎𝚝𝚜/ 存放你的輸出模板，而 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ 則存放你的風格指南。這些指令扮演著專案經理的角色，告訴 Agent 載入模板、讀取風格指南、向使用者詢問缺失的變數，然後填入文件。這對於生成可預測的 API 文件、標準化提交訊息，或搭建專案架構非常實用。
在這個技術報告生成器的範例中，技能檔案本身並不包含實際的版面配置或語法規則。它僅僅是協調這些資源的擷取，並強制 Agent 逐步執行它們：
1# skills/report-generator/SKILL.md2---3name: report-generator4description: 以 Markdown 格式產生結構化的技術報告。當使用者要求撰寫、建立或草擬報告、摘要或分析文件時使用。5metadata:6 pattern: generator7 output-format: markdown8---910你是一個技術報告生成器。請嚴格按照以下步驟操作：1112步驟 1：載入 'references/style-guide.md' 以了解語氣和格式化規則。1314步驟 2：載入 'assets/report-template.md' 以了解所需的輸出結構。1516步驟 3：向使用者詢問填寫模板所需的任何缺失資訊：17- 主題或標的18- 主要發現或數據點19- 目標受眾（技術人員、高層管理、一般大眾）2021步驟 4：根據風格指南規則填寫模板。輸出中必須包含模板中的每個章節。2223步驟 5：將完成的報告以單一 Markdown 文件回傳。
模式 3：Reviewer（審查員）
Reviewer 模式將「檢查的項目」與「檢查的方式」分開。你不必撰寫冗長的系統提示來詳述每一種程式碼壞味道，而是將一個模組化的評分標準存放在 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/𝚛𝚎𝚟𝚒𝚎𝚠-𝚌𝚑𝚎𝚌𝚔𝚕𝚒𝚜𝚝.𝚖𝚍 檔案中。
當使用者提交程式碼時，Agent 會載入這份檢查清單，並有條理地為提交的內容評分，將發現的問題按嚴重程度分組。如果你將 Python 風格的檢查清單換成 OWASP 安全檢查清單，就能使用完全相同的技能基礎架構，獲得一個完全不同且專門的審計結果。這是一種自動化 PR 審查或在人工檢查程式碼之前捕獲漏洞的高效方法。
以下的程式碼審查技能示範了這種分離。指令保持不變，但 Agent 會從外部檢查清單動態載入特定的審查標準，並強制產生結構化、基於嚴重程度的輸出：
1# skills/code-reviewer/SKILL.md2---3name: code-reviewer4description: 審查 Python 程式碼的品質、風格和常見錯誤。當使用者提交程式碼進行審查、請求對其程式碼提供回饋，或想要進行程式碼審計時使用。5metadata:6 pattern: reviewer7 severity-levels: error,warning,info8---910你是一個 Python 程式碼審查員。請嚴格按照此審查協議操作：1112步驟 1：載入 'references/review-checklist.md' 以獲取完整的審查標準。1314步驟 2：仔細閱讀使用者的程式碼。在批評之前先理解其目的。1516步驟 3：將檢查清單中的每一條規則應用於程式碼。對於發現的每個違規：17- 記錄行號（或近似位置）18- 分類嚴重程度：error（必須修復）、warning（應該修復）、info（建議考慮）19- 解釋為什麼這是個問題，而不只是說明什麼地方有問題20- 建議具體的修正方法和修正後的程式碼2122步驟 4：產生結構化的審查報告，包含以下章節：23- **摘要**：程式碼的功能概述、整體品質評估24- **發現**：按嚴重程度分組（先顯示 errors，接著是 warnings，最後是 info）25- **評分**：評分 1-10 分，附帶簡短理由26- **前 3 項建議**：最具影響力的改進項目
模式 4：Inversion（反向模式）
Agent 天生傾向於猜測並立即生成結果。Inversion 模式翻轉了這種動態。不再是使用者主導提示、Agent 執行任務，而是讓 Agent 扮演訪談者的角色。
Inversion 依賴於明確且不可協商的閘門指令（例如「在所有階段完成之前，不得開始建構」）來強制 Agent 先收集上下文。它會依序提出結構化的問題，並等待你的回答後才進入下一個階段。Agent 在完整了解你的需求和部署限制之前，會拒絕合成最終輸出。
來看看這個專案規劃技能的實際運作。這裡的關鍵在於嚴格的階段劃分，以及明確的守門提示，它會阻止 Agent 在收集完所有使用者回答之前合成最終計畫：
1# skills/project-planner/SKILL.md2---3name: project-planner4description: 透過結構化的問題收集需求，然後產出計畫來規劃一個新的軟體專案。當使用者說「我想建立」、「幫我規劃」、「設計一個系統」或「開始一個新專案」時使用。5metadata:6 pattern: inversion7 interaction: multi-turn8---910你正在進行一場結構化的需求訪談。在所有階段完成之前，不得開始建構或設計。1112## 階段 1 — 問題探索（一次問一個問題，等待每個答案）1314依序詢問這些問題。不要跳過任何問題。1516- Q1: 「這個專案為其使用者解決了什麼問題？」17- Q2: 「主要使用者是誰？他們的技術水準如何？」18- Q3: 「預期的規模是怎樣的？（每日使用者數、資料量、請求率）」1920## 階段 2 — 技術限制（僅在階段 1 完全回答後）2122- Q4: 「你會使用什麼部署環境？」23- Q5: 「你有任何技術棧需求或偏好嗎？」24- Q6: 「有哪些不可妥協的要求？（延遲、正常運行時間、合規性、預算）」2526## 階段 3 — 綜合（僅在所有問題都回答後）27281. 載入 'assets/plan-template.md' 以取得輸出格式292. 使用收集到的需求填寫模板中的每個章節303. 向使用者展示完成後的計畫314. 詢問：「這個計畫是否準確反映了你的需求？你想改變什麼？」325. 根據回饋進行迭代，直到使用者確認
模式 5：Pipeline（管線）
對於複雜的任務，你不能承受步驟被跳過或指令被忽略的風險。Pipeline 模式通過嚴格的檢查點來強制執行一個順序性的工作流程。
指令本身即充當工作流程的定義。通過實作明確的菱形閘門條件（例如在從 docstring 生成移動到最終組裝之前，需要使用者批准），Pipeline 確保 Agent 無法繞過複雜任務並直接呈現未經驗證的最終結果。
此模式運用了所有可選目錄，只在需要它們的特定步驟才拉取不同的參考檔案和模板，從而保持上下文視窗的乾淨。
在這個文件管線範例中，請注意明確的閘門條件。Agent 被明確禁止進入組裝階段，直到使用者確認了前一步驟生成的 docstring：
1# skills/doc-pipeline/SKILL.md2---3name: doc-pipeline4description: 透過多步驟管線從 Python 原始碼生成 API 文件。當使用者要求為模組建立文件、生成 API 文件，或從程式碼建立文件時使用。5metadata:6 pattern: pipeline7 steps: "4"8---910你正在執行一個文件生成管線。請按順序執行每個步驟。如果某個步驟失敗，不得跳過步驟或繼續進行。1112## 步驟 1 — 解析與盤點13分析使用者的 Python 程式碼，提取所有公開的類別、函式和常數。以檢查清單的形式呈現盤點結果。詢問：「這是你想要建立文件的完整公開 API 嗎？」1415## 步驟 2 — 生成 Docstring16對於每個缺少 docstring 的函式：17- 載入 'references/docstring-style.md' 以了解所需格式18- 嚴格按照風格指南生成 docstring19- 呈現每個生成的 docstring 供使用者批准20在使用者確認之前，不得進入步驟 3。2122## 步驟 3 — 組裝文件23載入 'assets/api-doc-template.md' 以了解輸出結構。將所有類別、函式和 docstring 編譯成單一的 API 參考文件。2425## 步驟 4 — 品質檢查26根據 'references/quality-checklist.md' 進行審查：27- 每個公開符號都已建立文件28- 每個參數都有型別和說明29- 每個函式至少有一個使用範例30報告結果。在呈現最終文件之前修復所有問題。
選擇正確的 Agent 技能模式
每種模式解決一個不同的問題。使用這個決策樹來為你的使用案例找到正確的模式：
最後，模式可以組合
這些模式並非互斥的。它們可以組合使用。
一個 Pipeline 技能可以在最後包含一個 Reviewer 步驟來雙重檢查其自身的工作。一個 Generator 可以在最開始依賴 Inversion 來收集必要的變數，然後再填入模板。得益於 ADK 的 𝕊𝕜𝕚𝕝𝕝𝕋𝕠𝕠𝕝𝕤𝕖𝕥 和漸進式揭露機制，你的 Agent 只會在運行時花費上下文令牌在它實際需要的模式上。
不要再試圖將複雜且脆弱的指令塞進單一的系統提示中。將你的工作流程拆解開來，套用正確的結構化模式，並打造可靠的 Agent。
立即開始
Agent Skills 規格是開源的，並且在 ADK 中原生支援。你已經知道如何打包格式。現在你知道了如何設計內容。現在就使用 Google Agent Development Kit 來打造更智慧的 Agent 吧。
