5 種每個 ADK 開發者都應知道的 Agent 技能設計模式

談到 𝚂𝙺𝙸𝙻𝙻.𝚖𝚍，開發者往往專注於格式——確保 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 慣例硬編碼到你的系統 Prompt 中，而是將它們打包成一個技能。你的 Agent 只有在實際使用該技術時才會載入此上下文。

這是最簡單的實作模式。𝚂𝙺𝙸𝙻𝙻.𝚖𝚍 檔案會監聽使用者 Prompt 中的特定程式庫關鍵字，從 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ 目錄動態載入你的內部文件，並將這些規則視為絕對真理來應用。這正是你將團隊的內部程式撰寫指南或特定框架最佳實踐直接分發到開發者工作流程中的機制。

以下是一個 Tool Wrapper 的範例，它教導 Agent 如何撰寫 FastAPI 程式碼。請注意，指令如何明確告知 Agent 僅在開始審閱或撰寫程式碼時才載入 𝚌𝚘𝚗𝚟𝚎𝚗𝚝𝚒𝚘𝚗𝚜.𝚖𝚍 檔案：

# skills/api-expert/SKILL.md
---
name: api-expert
description: FastAPI development best practices and conventions. Use when building, reviewing, or debugging FastAPI applications, REST APIs, or Pydantic models.
metadata:
  pattern: tool-wrapper
  domain: fastapi
---

You are an expert in FastAPI development. Apply these conventions to the user's code or question.

## Core Conventions

Load 'references/conventions.md' for the complete list of FastAPI best practices.

## When Reviewing Code
1. Load the conventions reference
2. Check the user's code against each convention
3. For each violation, cite the specific rule and suggest the fix

## When Writing Code
1. Load the conventions reference
2. Follow every convention exactly
3. Add type annotations to all function signatures
4. Use Annotated style for dependency injection

模式 2：Generator

Tool Wrapper 應用知識，而 Generator 則強制執行一致的輸出。如果你遇到 Agent 每次執行都產生不同文件結構的問題，Generator 透過協調一個填空過程來解決這個問題。

它利用兩個可選目錄：𝚊𝚜𝚜𝚎𝚝𝚜/ 存放你的輸出模板，而 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/ 存放你的風格指南。指令充當專案經理。它們告訴 Agent 載入模板、閱讀風格指南、向使用者詢問缺失的變數，然後填充文件。這對於產生可預測的 API 文件、標準化 commit 訊息或建構專案架構非常實用。

在這個技術報告產生器範例中，技能檔案不包含實際的佈局或語法規則。它只是協調這些資產的檢索，並強制 Agent 逐步執行它們：

# skills/report-generator/SKILL.md
---
name: report-generator
description: Generates structured technical reports in Markdown. Use when the user asks to write, create, or draft a report, summary, or analysis document.
metadata:
  pattern: generator
  output-format: markdown
---

You are a technical report generator. Follow these steps exactly:

Step 1: Load 'references/style-guide.md' for tone and formatting rules.

Step 2: Load 'assets/report-template.md' for the required output structure.

Step 3: Ask the user for any missing information needed to fill the template:
- Topic or subject
- Key findings or data points
- Target audience (technical, executive, general)

Step 4: Fill the template following the style guide rules. Every section in the template must be present in the output.

Step 5: Return the completed report as a single Markdown document.

模式 3：Reviewer

Reviewer 模式將要檢查的內容與如何檢查的內容分開。你無需撰寫冗長的系統 Prompt 來詳細說明每個程式異味，而是將模組化評分標準儲存在 𝚛𝚎𝚏𝚎𝚛𝚎𝚗𝚌𝚎𝚜/𝚛𝚎𝚟𝚒𝚎𝚠-𝚌𝚑𝚎𝚌𝚔𝚕𝚒𝚜𝚝.𝚖𝚍 檔案中。

當使用者提交程式碼時，Agent 會載入此清單並有條不紊地評分提交內容，按嚴重性對其發現進行分組。如果你將 Python 風格清單替換為 OWASP 安全清單，你將使用完全相同的技能基礎設施獲得一個完全不同、專業化的稽核。這是一種自動化 PR 審閱或在人工審閱程式碼之前捕捉漏洞的高效方式。

以下程式碼審閱者技能展示了這種分離。指令保持靜態，但 Agent 動態載入外部清單中的特定審閱標準，並強制產生結構化、基於嚴重性的輸出：

# skills/code-reviewer/SKILL.md
---
name: code-reviewer
description: Reviews Python code for quality, style, and common bugs. Use when the user submits code for review, asks for feedback on their code, or wants a code audit.
metadata:
  pattern: reviewer
  severity-levels: error,warning,info
---

You are a Python code reviewer. Follow this review protocol exactly:

Step 1: Load 'references/review-checklist.md' for the complete review criteria.

Step 2: Read the user's code carefully. Understand its purpose before critiquing.

Step 3: Apply each rule from the checklist to the code. For every violation found:
- Note the line number (or approximate location)
- Classify severity: error (must fix), warning (should fix), info (consider)
- Explain WHY it's a problem, not just WHAT is wrong
- Suggest a specific fix with corrected code

Step 4: Produce a structured review with these sections:
- **Summary**: What the code does, overall quality assessment
- **Findings**: Grouped by severity (errors first, then warnings, then info)
- **Score**: Rate 1-10 with brief justification
- **Top 3 Recommendations**: The most impactful improvements

模式 4：Inversion

Agent 本質上希望立即猜測並產生。Inversion 模式顛覆了這種動態。Agent 不再由使用者驅動 Prompt 並執行，而是充當採訪者。

Inversion 依賴明確、不可協商的門控指令（例如「在所有階段完成之前，請勿開始建構」）來強制 Agent 先收集上下文。它按順序提出結構化問題，並等待你的答案，然後再進入下一階段。Agent 拒絕合成最終輸出，直到它對你的需求和部署限制有完整的了解。

要看這個模式的實際應用，請看這個專案規劃者技能。這裡的關鍵要素是嚴格的分階段和明確的門控 Prompt，它阻止 Agent 合成最終計畫，直到收集所有使用者答案：

# skills/project-planner/SKILL.md
---
name: project-planner
description: Plans a new software project by gathering requirements through structured questions before producing a plan. Use when the user says "I want to build", "help me plan", "design a system", or "start a new project".
metadata:
  pattern: inversion
  interaction: multi-turn
---

You are conducting a structured requirements interview. DO NOT start building or designing until all phases are complete.

## Phase 1 — Problem Discovery (ask one question at a time, wait for each answer)

Ask these questions in order. Do not skip any.

- Q1: "What problem does this project solve for its users?"
- Q2: "Who are the primary users? What is their technical level?"
- Q3: "What is the expected scale? (users per day, data volume, request rate)"

## Phase 2 — Technical Constraints (only after Phase 1 is fully answered)

- Q4: "What deployment environment will you use?"
- Q5: "Do you have any technology stack requirements or preferences?"
- Q6: "What are the non-negotiable requirements? (latency, uptime, compliance, budget)"

## Phase 3 — Synthesis (only after all questions are answered)

1. Load 'assets/plan-template.md' for the output format
2. Fill in every section of the template using the gathered requirements
3. Present the completed plan to the user
4. Ask: "Does this plan accurately capture your requirements? What would you change?"
5. Iterate on feedback until the user confirms

模式 5：Pipeline

對於複雜任務，你不能容忍跳過步驟或忽略指令。Pipeline 模式強制執行嚴格、循序漸進的工作流程，並設有硬性檢查點。

指令本身充當工作流程定義。透過實施明確的菱形門控條件（例如在從 docstring 產生轉移到最終組裝之前要求使用者批准），Pipeline 確保 Agent 無法繞過複雜任務並呈現未經驗證的最終結果。

此模式利用所有可選目錄，僅在需要時引入不同的參考檔案和模板，保持上下文視窗整潔。

在這個文件管線範例中，請注意明確的門控條件。Agent 被明確禁止進入組裝階段，直到使用者確認上一步中產生的 docstring：

# skills/doc-pipeline/SKILL.md
---
name: doc-pipeline
description: Generates API documentation from Python source code through a multi-step pipeline. Use when the user asks to document a module, generate API docs, or create documentation from code.
metadata:
  pattern: pipeline
  steps: "4"
---

You are running a documentation generation pipeline. Execute each step in order. Do NOT skip steps or proceed if a step fails.

## Step 1 — Parse & Inventory
Analyze the user's Python code to extract all public classes, functions, and constants. Present the inventory as a checklist. Ask: "Is this the complete public API you want documented?"

## Step 2 — Generate Docstrings
For each function lacking a docstring:
- Load 'references/docstring-style.md' for the required format
- Generate a docstring following the style guide exactly
- Present each generated docstring for user approval
Do NOT proceed to Step 3 until the user confirms.

## Step 3 — Assemble Documentation
Load 'assets/api-doc-template.md' for the output structure. Compile all classes, functions, and docstrings into a single API reference document.

## Step 4 — Quality Check
Review against 'references/quality-checklist.md':
- Every public symbol documented
- Every parameter has a type and description
- At least one usage example per function
Report results. Fix issues before presenting the final document.

選擇正確的 Agent 技能模式

每種模式都回答不同的問題。使用此決策樹來找到適合你的使用案例的模式：

最後，模式可以組合

這些模式並非互斥。它們可以組合。

一個 Pipeline 技能可以在最後包含一個 Reviewer 步驟來再次檢查自己的工作。一個 Generator 可以在一開始就依賴 Inversion 來收集必要的變數，然後再填寫其模板。多虧了 ADK 的 SkillToolset 和漸進式揭露，你的 Agent 只會在執行時將 context token 花費在它所需的確切模式上。

停止嘗試將複雜且脆弱的指令塞入單一系統 Prompt。分解你的工作流程，應用正確的結構模式，並建構可靠的 Agent。

立即開始

Agent Skills 規範是開源的，並在 ADK 中原生支援。你已經知道如何打包格式。現在你知道如何設計內容了。使用 Google Agent Development Kit 建構更智慧的 Agent 吧。

在 X 上閱讀原文 ↗Gemini 翻譯