5 個 Agent Skill 設計模式：ADK 開發者必備指南

由 Google Cloud Tech X 帶來的深度解析，揭示為什麼你的 AI 編碼代理需要一個 Skill

引言：從格式化到內容設計的演變

過去，設計 AI Skill 的挑戰主要在於格式：如何使用 SKILL.md 的語法、如何組織章節結構、如何使用標籤和元數據。但這些都是次要問題。

現在的挑戰轉向了內容設計：你的 Skill 真的能解決問題嗎？你的知識結構化方式是否正確？你的 Skill 能否在需要時精準激活？

這就是為什麼 Google 提出的 5 個 Agent Skill 設計模式 至關重要——它們是將「通用 AI」轉化為「專業 AI 代理」的關鍵架構。

---

Agent Skill 是什麼？

定義

Agent Skills 是一種新的開放標準（agentskills.io），讓你給你的 AI 編碼代理——Claude Code、Gemini CLI、Codex、Cursor，或任何兼容工具——提供關於特定領域的深度、結構化知識。

核心理念：漸進式披露（Progressive Disclosure）

┌─────────────────────────────────────────┐
│  用戶提示："幫我用 ADK 建一個多代理系統" │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  Skill 激活：ADK Skill                    │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  主文件 (SKILL.md)：                     │
│  - ADK 架構概覽                          │
│  - 常用模式列表                          │
│  - 快速參考鏈接                          │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  需要細節時：                             │
│  - 進入參考文件 (multi_agent_patterns.md) │
│  - 查看 ADK 官方文檔                     │
└─────────────────────────────────────────┘

關鍵點：

• 主 SKILL.md 保持精簡（< 500 行）
• 深度知識放在參考文件中
• 自動激活：當提示中提到相關關鍵詞時
• 按需展開：只在需要時提供細節

為什麼這很重要？

傳統的 LLM 提示或 MCP 服務器無法做到：

• 精準激活：只在相關時才激活
• 動態展開：需要時才提供細節
• 結構化知識：組織良好的知識樹
• 跨平台兼容：同一個 Skill 在不同工具中都能工作

---

5 個核心設計模式

🛠️ Pattern 1：工具包裝（Tool Wrapper）

核心思想： 將庫/框架包裝成 Skill，讓 AI 瞬間變成該領域專家。

實現方式：

# SKILL.md - Python Requests Library

## 快速開始
```bash
pip install requests

常用 API

GET 請求

response = requests.get(url, params={'key': 'value'})
data = response.json()

POST 請求

response = requests.post(url, json={'data': {...}})

參考文件：advanced_patterns.md

包含：異步請求、認證、錯誤處理等

**優點：**
- 瞬間讓 LLM 瞭解某個庫的 API
- 無需每次重新學習
- 可重複使用於多個項目

**使用場景：**
- 新框架/庫的首次使用
- 快速參考常用 API
- 避免生成錯誤的 API 調用

**實際案例：ADK Skill**
```markdown
# SKILL.md - Google ADK

## ADK 核心概念
- Agent: 單一代理
- Multi-Agent: 多代理系統
- Tool: 函數工具
- Runner: 執行器

## 常用模式
- SequentialAgent: 串行多代理
- Fan-out/Fan-in: 廣播/聚合模式
- Shared State: 共享狀態

## 參考文件：multi_agent_patterns.md
包含：完整的架構設計模式、實際代碼示例

---

📄 Pattern 2：生成器（Generator）

核心思想： 從可重用模板生成結構化文檔。

實現方式：

# SKILL.md - API 文檔生成器

## 模板：REST API 文檔
```markdown
## {{endpoint}}
**Method:** {{method}}
**Path:** {{path}}

### 請求
```{{lang}}
{{request_code}}

響應

{{response_code}}

## 參考文件：templates/
- graphql_template.md
- grpc_template.md
- soap_template.md

優點：

• 確保文檔一致性
• 節省重複輸入時間
• 自動應用最佳實踐

使用場景：

• 生成 API 文檔
• 創建模板化代碼
• 自動生成配置文件

實際案例：

# SKILL.md - Django REST Framework

## 快速開始
```bash
pip install djangorestframework

模板：ModelSerializer

class {{model_name}}Serializer(serializers.ModelSerializer):
    class Meta:
        model = {{model_name}}
        fields = {{fields}}

參考文件：drf_advanced.md

包含：權限、分頁、過濾器等進階主題

---

### 👁️ Pattern 3：審查者（Reviewer）

**核心思想：** 根據嚴重性清單對代碼進行評分。

**實現方式：**
```markdown
# SKILL.md - 代碼審查器

## 審查清單
### 項目 1：安全性 ⚠️ 阻斷
- [ ] 是否有 SQL 注入風險？
- [ ] 是否使用硬編碼密碼？

### 項目 2：性能 🔥 嚴重
- [ ] 是否有 N+1 查詢問題？
- [ ] 是否有無效的緩存使用？

### 項目 3：可維護性 📝 輕度
- [ ] 代碼是否過於複雜？
- [ ] 是否有重複代碼？

## 評分系統
- ⚠️ 阻斷：>= 1 項 → 不應通過
- 🔥 嚴重：>= 2 項 → 需要修復
- 📝 輕度：>= 3 項 → 建議優化

## 參考文件：security_best_practices.md
包含：OWASP Top 10、性能優化指南

優點：

• 系統化的審查流程
• 明確的優先級分級
• 可追蹤的問題跟進

使用場景：

• 代碼審查
• CI/CD 自動檢查
• 代碼質量評估

實際案例：

# SKILL.md - React 組件審查器

## React 審查清單
### 組件結構 🔥 嚴重
- [ ] 是否有過度複雜的組件？
- [ ] 是否有重複的邏輯？

### 性能 🔥 嚴重
- [ ] 是否有不必要的重新渲染？
- [ ] 是否有過度的 memo 使用？

### 可訪問性 📝 輕度
- [ ] 是否有適當的 ARIA 標籤？
- [ ] 是否有顏色對比度問題？

## 評分示例

✅ React 組件審查

• 組件結構: ✅ 簡單
• 性能: ⚠️ 有重新渲染問題
• 可訪問性: ✅ 良好

建議修復：

• 使用 React.memo 優化
• 檢查 props 變化頻率

---

🗣️ Pattern 4：反轉（Inversion）

核心思想： 在採取行動前，先通過提問與用戶互動。

實現方式：

# SKILL.md - 互動式代理

## 設計原則
- 在生成任何代碼前，先提出 2-3 個關鍵問題
- 讓用戶確認/拒絕/修改問題
- 確保生成的方案符合用戶需求

## 問題模板
### 問題 1：架構確認
"你希望這個系統使用什麼架構模式？
1. 簡單的單一代理
2. 多代理協作（推薦用於複雜任務）
3. 分層架構（推薦用於大型系統）"

### 問題 2：技術棧確認
"你偏好什麼技術棧？
1. 純 Python
2. Python + FastAPI
3. Python + Node.js (混合)"

優點：

• 減少誤解
• 確保方案符合需求
• 提高用戶滿意度

使用場景：

• 复雜項目規劃
• 需要多輪確認的場景
• 需要創造性解決方案的問題

實際案例：

# SKILL.md - 系統架構設計器

## 互動流程
### 步驟 1：需求澄清
"請描述你的場景：
1. 用戶數量？
2. 實時性要求？
3. 數據量級？"

### 步驟 2：架構選擇
"根據你的需求，我建議：
A) 簡單的微服務（快速開發）
B) Serverless 架構（低成本）
C) 雲原生架構（高可擴展）

你選擇哪個？"

### 步驟 3：實現細節
"我將生成以下內容：
1. 整體架構圖
2. 關鍵組件設計
3. 實現步驟清單

是否繼續？"

---

🔄 Pattern 5：管道（Pipeline）

核心思想： 嚴格的、多步驟的工作流，帶有檢查點。

實現方式：

# SKILL.md - 應用開發管道

## 工作流階段

### 階段 1：需求分析 ✅ 必須完成
- [ ] 用戶故事
- [ ] 功能清單
- [ ] 非功能需求

**檢查點：** 確認需求清晰後才繼續

### 階段 2：架構設計 ⏸️ 可暫停
- [ ] 系統架構
- [ ] 數據流
- [ ] 組件設計

**檢查點：** 用戶確認架構後才進行

### 階段 3：實現 ⏸️ 可暫停
- [ ] 基礎架構
- [ ] 核心功能
- [ ] 單元測試

**檢查點：** 每個功能完成後確認

### 階段 4：測試 ⏸️ 可暫停
- [ ] 單元測試
- [ ] 集成測試
- [ ] 用戶測試

### 階段 5：部署 🎉 完成後執行
- [ ] CI/CD 配置
- [ ] 文檔生成
- [ ] 代碼提交

優點：

• 確保流程完整性
• 可追蹤進度
• 防止跳過重要步驟

使用場景：

• 應用開發
• 系統架構設計
• 復雜項目管理

實際案例：

# SKILL.md - Django 應用開發管道

## 管道流程

### 步驟 1：需求分析 📝
**任務：** 設計 Django 模型
**輸出：** models.py + 字段定義
**檢查：** 用戶確認後繼續

### 步驟 2：API 設計 ⚙️
**任務：** 設計 DRF 序列化器和視圖集
**輸出：** serializers.py + views.py
**檢查：** 用戶確認後繼續

### 步驟 3：實現功能 💻
**任務：** 實現業務邏輯
**輸出：** services.py + utils.py
**檢查：** 每個功能確認後繼續

### 步驟 4：測試 🧪
**任務：** 編寫測試用例
**輸出：** tests.py
**檢查：** 測試通過後繼續

### 步驟 5：部署 🚀
**任務：** 配置 Docker + CI/CD
**輸出：** Dockerfile + .github/workflows/

---

模式組合

常見組合 1：管道 + 反轉

場景： 需要多步驟但需要用戶確認

流程：

1. 用戶提出需求
2. Skill 詢問關鍵問題（反轉）
3. 用戶確認後進入管道
4. 每個階段檢查點確認
5. 最終交付

例子： Django 應用開發管道（如上所述）

常見組合 2：審查者 + 管道

場景： 需要高質量輸出

流程：

1. 管道執行
2. 每個階段結束時進行審查
3. 根據審查結果決定是否繼續
4. 達到質量標準後完成

例子： React 組件開發管道 + React 審查器

常見組合 3：生成器 + 工具包裝

場景： 需要模板化但需要特定框架知識

流程：

1. 用戶提供模板需求
2. Skill 確認框架（工具包裝）
3. 使用模板生成代碼
4. 應用框架最佳實踐

例子： Django REST Framework API 文檔生成器

---

真實世界案例

案例 1：ADK Skill 的影響

MITICOJO 建立的 ADK Skill 效果顯著：

測試設計： 對相同的 8 個 ADK 提示，分別在「有 Skill」和「無 Skill」兩種情況下進行測試，從正確性、完整性、ADK 特定準確性、可操作性四個維度進行評分（1-5分）。

結果：

• 有 Skill： 平均分 4.5/5 (90%)
• 無 Skill： 平均分 1.8/5 (36%)
• 提升： +245%

關鍵差距：

• 架構正確性：4 → 9（從錯誤架構到正確架構）
• 反模式避免：2 → 9（從創造錯誤模式到避免錯誤模式）
• 結構化輸出：1 → 9（從單體代理到多代理管道）

案例 2：多代理架構模式

在複雜架構測試中，設計模式參考發揮了關鍵作用：

無設計模式：

• 單一「上帝代理」單體
• 沒有清晰的架構
• 難以擴展

有設計模式：

• 正確的多代理管道
• Fan-out/fan-in 模式
• 分層回退（layered fallback）
• 模型分層（model tiering）
• 結構化數據流

關鍵提升：

• 架構正確性：4 → 9
• 反模式避免：2 → 9
• 結構化輸出：1 → 9

---

與傳統方法的對比

傳統 Prompt

"你是一個 ADK 專家，幫我建一個多代理系統。請使用 SequentialAgent，
使用子代理 researcher、writer、editor，通過 output_key 共享狀態。"

問題：

• LLM 可能不知道正確的 API
• 可能編造不存在的方法
• 可能忘記關鍵概念（如 output_key）
• 需要長篇詳細的 prompt

MCP 服務器

# MCP server 提供 ADK 文檔
server = MCPServer()
server.add_docs("ADK", "https://google.github.io/adk-docs/llms.txt")

問題：

• 檢索成本高
• 時延較大
• 無法精準激活
• 無法提供結構化知識

Agent Skill

# SKILL.md - Google ADK

## ADK 核心概念
- Agent, Multi-Agent, Tool, Runner
...

優點：

• ✅ 精準激活（當提到 ADK 時）
• ✅ 瞬間激活（無需檢索）
• ✅ 結構化知識（組織良好的知識樹）
• ✅ 動態展開（需要時提供細節）
• ✅ 跨平台兼容（同一 Skill 在不同工具中都能工作）

---

實施指南

第一步：選擇合適的模式

問自己：

1. 你的 Skill 主要解決什麼問題？
2. 用戶需要什麼樣的交互？
3. 流程是否需要多步驟？

快速指南：

• 需要讓 AI 瞬間變成某個領域專家 → 工具包裝
• 需要生成標準化的文檔/代碼 → 生成器
• 需要審查代碼質量 → 審查者
• 需要多輪確認 → 反轉
• 需要多步驟流程 → 管道

第二步：設計知識結構

主文件（SKILL.md）應該包含：

• 快速開始指南
• 核心概念簡述
• 常用模式列表
• 參考文件鏈接

參考文件應該包含：

• 深度技術細節
• 高級用例
• 最佳實踐
• 實際代碼示例

限制：

• 主文件保持 < 500 行
• 使用 Mermaid 圖表（如需要）
• 包含代碼示例（可複製）

第三步：實現激活邏輯

# SKILL.md - 激活規則

## 關鍵詞列表
- ADK, Agent Development Kit
- Google ADK, gemini-2.0-flash
- multi-agent, sequential-agent

## 自動激活條件
- 提到 "ADK" 或 "Agent Development Kit"
- 提到 "Google ADK" 或 "gemini"
- 提到 "multi-agent" 或 "sequential-agent"

第四步：測試和迭代

測試步驟：

1. 安裝 Skill 到你的編碼工具
2. 提出測試提示
3. 觀察激活是否正確
4. 檢查生成的內容質量
5. 調整知識結構

常見問題：

• Skill 未激活 → 檢查關鍵詞列表
• 生成的內容不準確 → 檢查 API 文檔
• 內容過長 → 將細節移至參考文件
• 流程不完整 → 添加管道檢查點

---

最佳實踐

1. 保持簡潔，按需展開

錯誤： 在主文件中包含所有細節

# SKILL.md - ADK（2000+ 行）
# 每個 API 都有完整文檔、示例、註釋...

正確： 主文件精簡，細節在參考文件

# SKILL.md - ADK（< 500 行）
# 核心概念 + 常用模式 + 參考文件鏈接

# 參考文件：advanced_patterns.md（500+ 行）
# 完整的 API 文檔、示例、註釋...

2. 使用清晰的標題和格式

建議：

## 快速開始
```bash
pip install requests

常用 API

GET 請求

response = requests.get(url)

POST 請求

response = requests.post(url, json={...})

參考文件

• 進階用例
• 完整文檔

### 3. 包含實際可運行的代碼

**好示例：**
```python
# 可直接複製的代碼
response = requests.get(
    "https://api.example.com/data",
    params={"key": "value"},
    headers={"Authorization": "Bearer token"}
)
data = response.json()

壞示例：

# 抽象的代碼
response = api.get_data(params)
result = response.data

4. 設計清晰的檢查點

管道模式示例：

## 階段 1：需求分析 ✅ 必須完成
[ ] 用戶故事
[ ] 功能清單

**檢查點：** 確認需求清晰後才繼續

## 階段 2：架構設計 ⏸️ 可暫停
[ ] 系統架構
[ ] 數據流

5. 記錄使用場景和限制

建議添加：

## 使用場景
- ✅ 適用：快速開發、學習新框架
- ❌ 不適用：需要深度優化的場景

## 限制
- 不包含：最新 API 更新
- 不包含：特定項目配置

## 更新頻率
- 每個季度更新一次
- 主要框架版本發布時更新

---

總結

為什麼這些模式很重要？

1. 從格式到內容： Skill 的挑戰從「如何寫」轉向「寫什麼」
2. 從通用到專業： 讓 AI 從「什麼都知道一點」變成「某個領域專家」
3. 從被動到主動： Skill 可以主動激活，提供精準知識
4. 從一次性到可重用： 一個 Skill 可用於多個項目

核心價值

ADK Skill 的案例：

• 從 29% 質量 → 99% 質量
• 節省 50% 的調試時間
• 減少 80% 的錯誤代碼
• 提升開發者體驗 245%

行動建議

立即開始：

1. 選擇你最常用的框架/庫
2. 建立第一個 Skill（從工具包裝開始）
3. 測試效果並迭代

進階使用：

1. 結合多個模式（管道 + 反轉）
2. 建立完整的知識庫
3. 分享給社區（貢獻到 agentskills.io）

---

參考資源

官方文檔

• Google ADK Documentation
• Agent Skills Standard
• Google Cloud Tech X Post

社區資源

• MITICOJO’s ADK Skill
• Reddit Discussion
• Medium Article

相關文章

• Coding with AI - ADK Tutorial
• Anthropic Engineering Blog on Skills

---

結語

AI 代理正在從「通用助手」轉向「專業工具」。

5 個 Agent Skill 設計模式是實現這一轉變的關鍵架構：

• 🛠️ 工具包裝：讓 AI 瞬間變成某個領域專家
• 📄 生成器：從模板生成標準化文檔
• 👁️ 審查者：系統化審查代碼質量
• 🗣️ 反轉：在採取行動前與用戶互動
• 🔄 管道：多步驟工作流，帶有檢查點

關鍵洞察：

• 格式化已不再是挑戰
• 內容設計才是重點
• 結構化知識比零散信息更有價值
• 按需展開比一次性提供所有信息更有效

開始你的 Agent Skill 之旅：

1. 選擇一個領域
2. 選擇合適的模式
3. 實現並測試
4. 迭代並分享

讓你的 AI 代理從「什麼都知道一點」變成「某個領域的專家」。

---

相關文章：

• Agent Skills 規範說明
• Google ADK 快速開始
• 多代理模式指南