Google 實踐分享：5 種 AI Agent Skill 設計模式

如果將 Agent 比喻成一個新同事，咁 Tool 就好似佢嘅手腳，Skill 就好似佢嘅工作手冊。

Tool 解決嘅係「做唔做到」。 Skill 解決嘅係「應該點樣做」。

例如，一個 Tool 係「叫天氣 API」；而一個 Skill 就係「當用戶想規劃旅行時，先查幾個城市嘅天氣，再比較，最後跟行程場景整理成建議」。前者提供能力，後者提供方法。

喺 ADK 入面，Skill 仲有一個好重要嘅工程價值：佢支援按需要加載。系統啟動時，先只俾模型見到 Skill 嘅名同描述；真正需要嘅時候，先至加載完整說明、參考文件同模板。咁做既可以節省上下文，又唔使 Agent 成日背住一大堆無關規範喺腦度。

所以，Skill 唔係「長啲嘅 Prompt」，而係可重用、可組合、可按需要調用嘅經驗模塊。

Google資深工程師Lavi Nigam 不斷強調一個好現實嘅問題：同樣都叫 SKILL.md，入面嘅寫法可以完全唔同。

有啲 Skill 適合放入某個框架嘅開發規範，有啲適合穩定輸出固定格式嘅文件，有啲適合拎住清單做審查，仲有啲根本唔應該一開始就輸出，而係應該反過嚟向用戶問問題。

即係話，Skill 嘅難處唔係目錄點樣，而係你要先判斷：今次你需要嘅，究竟係一本「規則手冊」、一份「輸出模板」、一張「檢查清單」、一套「訪談劇本」，定係一條「有檢查點嘅流水線」。

呢個都係呢篇文章最有價值嘅地方。佢冇停留喺「Skill 可以做啲咩」，而係進一步回答咗「咩問題，適合用咩結構嚟做」。

呢個係五種模式入面最基礎嘅一種，通常都係最容易上手嘅一種。

佢嘅核心思路好簡單：將某個 Library、Framework、內部平台或者團隊規範，包裝成一個按需要加載嘅知識包。用戶一提出相關任務，Agent 就會加載呢套規則，然後跟住呢套規則嚟寫 Code、做 Review 或者俾建議。

Tool Wrapper 原理圖

你可以理解成「專業手冊外掛」。

例如，用戶正在寫 FastAPI 接口。普通 Agent 可能識得啲 FastAPI 常識，但寫寫嚇就好易撈亂其他 Framework 嘅習慣。但如果你預先做咗個 Tool Wrapper，將路由規範、依賴注入方式、異常處理原則、類型註解要求放曬入 references/ 度，咁 Agent 喺觸發呢個 Skill 之後，就會更加似一個真正識 FastAPI 約定嘅開發者。

最細例子：

---
name: api-expert
description: FastAPI 開發最佳實踐與約定。用於編寫、審查或排查 FastAPI 應用、REST API 與 Pydantic 模型。
metadata:
pattern: tool-wrapper
domain: fastapi
---
你是一名 FastAPI 開發專家。
先加載 `references/conventions.md`，再按規範寫代碼或做審查。

呢種模式特別適合三類場景：

• 特定技術棧嘅開發規範，例如 FastAPI、React、Terraform
• 團隊內部嘅工程約定，例如命名、目錄結構、模型選擇規則
• 某個 SDK 或平台嘅最佳實踐，例如 API 調用方式同安全邊界

文章入面仲特別提到一個容易忽略嘅細節：Skill 嘅 description 好緊要。佢唔係裝飾，而係 Agent 嘅檢索入口。寫得太濫，Skill 就觸發唔到；寫得具體，Agent 先知道幾時要拎呢本「手冊」出嚟。

如果 Tool Wrapper 解決嘅係「點樣遵守規則」，咁 Generator 解決嘅就係「結果點樣穩定產出”。

好多人都有呢個經驗：叫模型寫一篇報告，今日結構完整，聽日又左一鎚右一棍；今日正式，聽日又似傾偈記錄。根本原因唔係模型唔識寫，而係輸出結構冇固定落嚟。

Generator 原理圖

Generator 模式嘅做法係將兩件事分開：

• 用 assets/ 放模板，規定結果要有邊啲部分
• 用 references/ 放風格指南，規定呢啲部分應該點樣寫

模板負責結構，風格指南負責質量。

咁樣一嚟，Skill 嘅運作方式就好似填表。先加載模板，確認目標產物嘅章節；再加載風格要求，確認語氣、篇幅、格式；如果關鍵資訊唔夠，就繼續向用戶追問；最後先將內容完整填返入去。

最細例子：

---
name: report-generator
description: 生成結構化技術報告。適用於報告、總結或分析文檔。
metadata:
pattern: generator
output-format: markdown
---
1. 加載 `references/style-guide.md`
2. 加載 `assets/report-template.md`
3. 詢問缺失信息後，按模板輸出完整文檔

呢類模式非常適合：

• 技術報告
• API 文件
• 標準化週報
• 固定格式嘅提交訊息
• Agent 項目腳手架

佢嘅底層邏輯其實好工程化：將「點樣寫」由一次次現場發揮，變成一 set 可重複執行嘅生產動作。

如果你叫一個 Agent「幫我 Review 嚇啲 Code」，佢多數都講到啲問題，但亦好易漏咗關鍵缺陷，或者將注意力放喺啲唔痛不癢嘅小問題上。

Reviewer 模式就係為咗解決呢個問題。

佢最重要嘅設計思想係將兩件事徹底拆開：

• 「檢查啲咩」，放落 references/ 嘅 checklist
• 「點樣檢查」，寫入 SKILL.md 嘅執行流程

咁樣，Skill 就唔係靠模型直覺做評審，而係拎住清單逐條 check。

Reviewer 原理圖

文章入面嘅例子就係典型：Code Review Skill 會先加載審查清單，再去理解用戶嘅 Code，然後按嚴重程度輸出問題，例如邊啲屬於一定要修嘅錯誤、邊啲係應該優化嘅警告、邊啲只係建議。更重要嘅係，佢仲要求俾理由、位置同修復建議，而唔係淨係話「呢度唔係幾好」。

最細例子：

---
name: code-reviewer
description: 審查 Python 代碼質量、風格和常見缺陷。
metadata:
pattern: reviewer
severity-levels: error,warning,info
---
1. 加載 `references/review-checklist.md`
2. 先理解代碼用途，再逐條檢查
3. 輸出摘要、問題列表、評分和改進建議

呢類模式適合嘅範圍其實好廣：

• Code Review
• 安全審計
• 文件質量檢查
• 內容編輯審校
• 團隊規範合規性檢查

佢嘅優勢係穩定。只要清單唔變，審查標準就唔會飄。團隊終於可以將「資深工程師腦入面嘅經驗」沉澱成一 set 大家都可以重用嘅判斷標準。

呢個係五種模式入面最值得一般團隊盡快引入嘅一種。

好多 Agent 失敗，唔係因為模型唔夠聰明，而係因為佢太心急。用戶淨係講咗句「幫我做個系統」，佢就已經開始輸出架構圖、技術棧同實施方案。睇落好積極，但實際上全部都係靠假設嚟「自信亂答」。

Inversion 模式就係反轉嚟設計對話：唔係用戶一路帶住 Agent 輸出，而係 Agent 先進入訪問模式，一輪一輪將必要資訊問齊，然後先開始產生結果。

Inversion 原理圖

佢嘅關鍵唔係「問多幾個問題」，而係要設定清晰嘅階段同硬性門檻。例如第一階段問業務目標，第二階段問技術限制，第三階段先準綜合輸出。文章特別強調，好似「所有階段完成前唔好開始構建」呢類限制句子好緊要，否則 Agent 好多時攞到第一個答案就忍唔住提早落結論。

最細例子：

---
name: project-planner
description: 先通過結構化提問收集需求，再輸出項目規劃。
metadata:
pattern: inversion
interaction: multi-turn
---
在所有階段完成前，不要開始設計或構建。
第一階段問問題，第二階段問約束，最後才綜合輸出。

呢種模式非常適合：

• 需求訪談
• 故障排查
• 設定精靈
• 方案設計前嘅資料收集
• 新 Agent 嘅需求確認

佢嘅真正價值係將「靠估計輸出」改成「靠已確認資訊輸出」。好多時候，Agent 質量嘅提升，並唔係嚟自更強嘅模型，而係嚟自更嚴格嘅提問順序。

如果前四種模式更加似單點能力，咁 Pipeline 就更加似一套完整工作流程。

佢適合處理嗰啲明顯有先後依賴關係嘅任務。前一步未做完，後一步就唔應該開始；中間做少一步，最終結果就可能唔可靠。

文章俾嘅例子係自動產生文件：

第一步，先解析 Code，列出需要寫文件嘅公共對象。 第二步，再跟規範補齊文件字串。 第三步，將內容裝配入統一模板。 第四步，按質量清單檢查係咪有缺漏、係咪合規。

Pipeline 原理圖

呢度最緊要嘅唔係「分咗四步」，而係每一步之間都有 gate，即係檢查點。例如第二步生成完 docstring 之後，一定要等用戶確認，先可以進入第三步。冇呢啲檢查點，Agent 好多時會一口氣衝到最後，睇落效率好高，但實際上 skip 咗驗證環節。

最細例子：

---
name: doc-pipeline
description: 通過多階段流水線，從 Python 源碼生成 API 文檔。
metadata:
pattern: pipeline
steps:"4"
---
按順序執行每一步；任何一步失敗都不要往下走。
生成 docstring 後，必須等待用戶確認，再進入下一步。

Pipeline 模式通常會同時用到三類資源：

• references/ ：提供規則
• assets/：提供模板

• scripts/：支持執行具體腳本

佢係五種模式入面最重嘅一種，但亦最似真正嘅生產流程。凡是涉及「順序、依賴、校驗、人類確認」嘅任務，都應該優先考慮 Pipeline。

模式選擇判斷圖

• 如果你嘅目標係想 Agent 學識某個技術棧或內部規範，用 Tool Wrapper。

• 如果你嘅目標係令輸出長期保持固定結構，用 Generator。

• 如果你嘅目標係想 Agent 跟標準做評審，用 Reviewer。

• 如果你嘅目標係先補齊上下文、避免盲估，用 Inversion。

• 如果你嘅目標係行一條唔可以跳步嘅多階段流程，用 Pipeline。

呢五種模式並唔係互相排斥。相反，文章明確提到，真實生產環境入面好多時會組合用兩到三種模式。

例如，一個「新項目啟動助手」完全可以咁樣設計：先用 Inversion 訪談需求，再用 Generator 生成方案文件，最後用 Reviewer 對方案做一次規則檢查。如果成個流程仲有審批節點，咁佢本身又會變成一條 Pipeline。

Lavi Nigam 呢篇文章最值得重視嘅，唔止佢列出五個模式，而係將一個趨勢講清楚咗：

Agent 開發正由「寫 Prompt」走向「做工程設計」。

以前，好多人優化 Agent，靠嘅係不斷補系統提示詞；而家，越來越多團隊開始將規範、模板、清單同流程拆出嚟，做成可維護、可組合、可搬遷嘅 Skill。咁做嘅好處好直接：

• 經驗可以重用，唔使每次都由頭講過
• 輸出更穩定，唔靠模型臨場發揮
• 上下文更慳，唔需要將所有資訊一次過塞曬入去
• 團隊協作更容易，因為規則有個地方落地

文章仲提到，採用 SKILL.md 規範嘅 Agent 工具已經有 30 幾種。即係話 Skill 唔止係某個 Framework 入面嘅小技巧，而係慢慢變成一種跨工具重用嘅工程資產。

下次如果你嘅 Agent 輸出唔穩定，先唔好怪個模型唔夠強。

先問自己一句：你缺嘅到底係一個更大嘅模型，定係一個更啱嘅 Skill 結構？

好多時候，真正令 Agent 變穩定嘅，唔係再駁多一個 Tool，而係終於將「經驗」寫成咗「方法」。

如果把 Agent 比作一個新人同事，那麼 Tool 更像他的手和腳，Skill 更像他的工作手冊。

Tool 解決的是“能不能做”。 Skill 解決的是“該怎麼做”。

比如，一個 Tool 是“調用天氣 API”；而一個 Skill 則是“當用戶要規劃旅行時，先查詢多個城市天氣，再進行對比，最後按行程場景整理成建議”。前者提供能力，後者提供方法。

在 ADK 裏，Skill 還有一個很關鍵的工程價值：它支持按需加載。系統啓動時，先只讓模型看到 Skill 的名稱和描述；真正需要時，再去加載完整說明、參考文檔和模板。這樣做既節省上下文，也讓 Agent 不必把一大堆無關規範一直背在腦子裏。

所以，Skill 不是“更長一點的 Prompt”，而是可複用、可組合、可按需調用的經驗模塊。

Google資深工程師Lavi Nigam 反覆強調一個很現實的問題：同樣都叫 SKILL.md，它們內部的寫法可以完全不同。

有的 Skill 適合裝進某個框架的開發規範，有的適合穩定輸出固定格式的文檔，有的適合拿着清單做審查，還有的根本不該上來就輸出，而應該先反過來向用戶提問。

也就是說，Skill 的難點並不是目錄長什麼樣，而是你要先判斷：這次你需要的，究竟是一本“規則手冊”、一份“輸出模板”、一張“檢查清單”、一套“訪談腳本”，還是一條“有檢查點的流水線”。

這也是這篇文章最有價值的地方。它沒有停留在“Skill 可以做什麼”，而是進一步回答了“什麼問題，適合用什麼結構來做”。

這是五種模式裏最基礎的一種，也通常是最好上手的一種。

它的核心思路很簡單：把某個庫、框架、內部平台或團隊規範，打包成一個按需加載的知識包。用戶一旦提出相關任務，Agent 就去加載這套規則，然後按這套規則來寫代碼、做 Review 或給建議。

Tool Wrapper 原理圖

你可以把它理解成“專業手冊外掛”。

比如，用戶正在寫 FastAPI 接口。普通 Agent 可能知道一些 FastAPI 常識，但寫着寫着就容易混進別的框架習慣。可如果你提前做了一個 Tool Wrapper，把路由規範、依賴注入方式、異常處理原則、類型註解要求都放進 references/ 裏，那麼 Agent 在觸發這個 Skill 後，就會更像一個真正懂 FastAPI 約定的開發者。

最小示例：

---
name: api-expert
description: FastAPI 開發最佳實踐與約定。用於編寫、審查或排查 FastAPI 應用、REST API 與 Pydantic 模型。
metadata:
pattern: tool-wrapper
domain: fastapi
---
你是一名 FastAPI 開發專家。
先加載 `references/conventions.md`，再按規範寫代碼或做審查。

這種模式特別適合三類場景：

• 特定技術棧的開發規範，比如 FastAPI、React、Terraform
• 團隊內部的工程約定，比如命名、目錄結構、模型選擇規則
• 某個 SDK 或平台的最佳實踐，比如 API 調用方式和安全邊界

文章裏還特別提到一個容易被忽略的細節：Skill 的 description 非常關鍵。它不是裝飾，而是 Agent 的檢索入口。寫得太泛，Skill 就觸發不了；寫得具體，Agent 才知道什麼時候該把這本“手冊”翻出來。

如果 Tool Wrapper 解決的是“規則怎麼遵守”，那麼 Generator 解決的就是“結果怎麼穩定產出”。

很多人都遇到過這種情況：讓模型寫一篇報告，今天結構完整，明天又東一榔頭西一棒槌；今天偏正式，明天又像聊天記錄。根本原因不是模型不會寫，而是輸出結構沒有被固定下來。

Generator 原理圖

Generator 模式的做法是把兩件事分開：

• 用 assets/ 放模板，規定結果必須有哪些部分
• 用 references/ 放風格指南，規定這些部分應該怎麼寫

模板負責結構，風格指南負責質量。

這樣一來，Skill 的工作方式就很像填表。先加載模板，確認目標產物的章節；再加載風格要求，確認語氣、篇幅、格式；如果關鍵信息不足，就繼續向用戶追問；最後再把內容完整填進去。

最小示例：

---
name: report-generator
description: 生成結構化技術報告。適用於報告、總結或分析文檔。
metadata:
pattern: generator
output-format: markdown
---
1. 加載 `references/style-guide.md`
2. 加載 `assets/report-template.md`
3. 詢問缺失信息後，按模板輸出完整文檔

這類模式非常適合：

• 技術報告
• API 文檔
• 標準化週報
• 固定格式的提交信息
• Agent 項目腳手架

它的底層邏輯其實很工程化：把“怎麼寫”從一次次現場發揮，變成一套可重複執行的生產動作。

如果你讓一個 Agent “幫我 Review 一下代碼”，它大概率能說出一些問題，但也很容易漏掉關鍵缺陷，或者把注意力花在不痛不癢的小毛病上。

Reviewer 模式就是為了解決這個問題。

它最重要的設計思想是把兩件事徹底拆開：

• “檢查什麼”，放進 references/ 裏的 checklist
• “如何檢查”，寫進 SKILL.md 的執行流程

這樣，Skill 不再是憑模型直覺做評審，而是拿着清單逐條過。

Reviewer 原理圖

文章裏的例子就很典型：代碼評審 Skill 會先加載審查清單，再去理解用戶代碼，然後按嚴重程度輸出問題，比如哪些屬於必須修復的錯誤，哪些是應該優化的警告，哪些只是建議。更重要的是，它還要求給出原因、位置和修復建議，而不是隻說一句“這裏不太好”。

最小示例：

---
name: code-reviewer
description: 審查 Python 代碼質量、風格和常見缺陷。
metadata:
pattern: reviewer
severity-levels: error,warning,info
---
1. 加載 `references/review-checklist.md`
2. 先理解代碼用途，再逐條檢查
3. 輸出摘要、問題列表、評分和改進建議

這類模式適合的範圍其實非常廣：

• 代碼評審
• 安全審計
• 文檔質量檢查
• 內容編輯審校
• 團隊規範合規性檢查

它的優勢在於穩定。只要清單不變，審查標準就不會飄。團隊也終於可以把“資深工程師腦子裏的經驗”沉澱成一套大家都能複用的判斷標準。

這是五種模式裏最值得普通團隊儘快引入的一種。

很多 Agent 失敗，不是因為模型不夠聰明，而是因為它太着急。用戶只說了一句“幫我做個系統”，它就已經開始輸出架構圖、技術棧和實施方案了。看起來很積極，實際上全是建立在假設上的“自信亂答”。

Inversion 模式就是反過來設計對話：不是用戶一路驅動 Agent 輸出，而是 Agent 先進入採訪模式，一輪一輪把必要信息問全，然後才開始生成結果。

Inversion 原理圖

它的關鍵不是“多問幾個問題”，而是要設置清晰的階段和硬性門檻。比如第一階段問業務目標，第二階段問技術約束，第三階段才允許綜合輸出。文章特別強調，像“所有階段完成前不要開始構建”這樣的限制語句非常關鍵，否則 Agent 往往在拿到第一個答案後就忍不住提前下結論。

最小示例：

---
name: project-planner
description: 先通過結構化提問收集需求，再輸出項目規劃。
metadata:
pattern: inversion
interaction: multi-turn
---
在所有階段完成前，不要開始設計或構建。
第一階段問問題，第二階段問約束，最後才綜合輸出。

這種模式非常適合：

• 需求訪談
• 故障排查
• 配置嚮導
• 方案設計前的信息採集
• 新 Agent 的需求確認

它的真正價值，是把“基於猜測輸出”改成“基於已確認信息輸出”。很多時候，Agent 質量的提升，並不來自更強的模型，而來自更嚴格的提問順序。

如果前四種模式更像單點能力，那麼 Pipeline 更像一套完整工作流。

它適合處理那種明顯有先後依賴關係的任務。前一步不完成，後一步就不該開始；中間少做一步，最終結果就可能不可靠。

文章給出的例子是自動生成文檔：

第一步，先解析代碼，列出需要被文檔化的公共對象。 第二步，再根據規範補全文檔字符串。 第三步，把內容裝配進統一模板。 第四步，按質量清單檢查是否缺項、是否合規。

Pipeline 原理圖

這裏最關鍵的不是“分成四步”，而是每一步之間都有 gate，也就是檢查點。比如第二步生成完 docstring 後，必須等用戶確認，才能進入第三步。沒有這些檢查點，Agent 往往會一口氣衝到最後，看起來效率很高，實際上跳過了驗證環節。

最小示例：

---
name: doc-pipeline
description: 通過多階段流水線，從 Python 源碼生成 API 文檔。
metadata:
pattern: pipeline
steps:"4"
---
按順序執行每一步；任何一步失敗都不要往下走。
生成 docstring 後，必須等待用戶確認，再進入下一步。

Pipeline 模式通常會同時用到三類資源：

• references/ ：提供規則
• assets/：提供模板

• scripts/：支持執行具體腳本

它是五種模式裏最重的一種，但也最像真正的生產流程。凡是涉及“順序、依賴、校驗、人類確認”的任務，都應該優先考慮 Pipeline。

模式選擇判斷圖

• 如果你的目標是讓 Agent 學會某個技術棧或內部規範，用 Tool Wrapper。

• 如果你的目標是讓輸出長期保持固定結構，用 Generator。

• 如果你的目標是讓 Agent 按標準做評審，用 Reviewer。

• 如果你的目標是先補齊上下文、避免盲猜，用 Inversion。

• 如果你的目標是跑一條不能跳步的多階段流程，用 Pipeline。

這五種模式不是互斥關係。相反，文章明確提到，真實生產環境裏往往會組合使用兩到三種模式。

比如，一個“新項目啓動助手”完全可以這樣設計：先用 Inversion 訪談需求，再用 Generator 生成方案文檔，最後用 Reviewer 對方案做一次規則檢查。如果整個流程還帶審批節點，那它本身又會變成一條 Pipeline。

Lavi Nigam 這篇文章最值得重視的，不只是列出五個模式，而是把一個趨勢講透了：

Agent 開發正在從“寫 Prompt”走向“做工程設計”。

過去，很多人優化 Agent，靠的是不斷補系統提示詞；現在，越來越多團隊開始把規範、模板、清單和流程拆出來，做成可維護、可組合、可遷移的 Skill。這樣做的好處很直接：

• 經驗可以複用，不必每次從頭講
• 輸出更穩定，不靠模型臨場發揮
• 上下文更省，不需要把所有信息一次性塞進去
• 團隊協作更容易，因為規則有地方落地

文章還提到，採用 SKILL.md 規範的 Agent 工具已經有 30 多種。這意味着 Skill 不只是某個框架裏的小技巧，而是在逐漸變成一種跨工具複用的工程資產。

下次如果你的 Agent 輸出不穩定，先別急着怪模型不夠強。

先問自己一句：你缺的到底是一個更大的模型，還是一個更對的 Skill 結構？

很多時候，真正讓 Agent 變穩的，不是再多接一個工具，而是終於把“經驗”寫成了“方法”。