Agent Skill 設計與實戰：從 N*N 工具流到智能聚合

前言：你可能已經會的東西

如果你正在使用 Claude Code，你大概寫過這樣的 Skills：

---
name: research
description: 網路研究專家
triggers:
  - "研究"
  - "research"
tools:
  - WebSearch
  - WebFetch
---

這個 Skill 幫你研究任何主題...

簡單、宣告式、直觀 - 這就是 Claude Code Skills 的魅力。

但你可能不知道：

同樣的「宣告式 Skill」概念可以解決 N*N 工具鏈問題。

第一部分：你可能遇到的問題

1.1 傳統開發流程的痛點

搜集資料 → 人工挑選 → 產出資料
    ↓          ↓          ↓
  Tool A    判斷步驟    Tool B

問題：

❌ 每個步驟需要人工介入
❌ 工具間連接困難
❌ N 個工具 = N! 種組合
❌ 難以維護和擴展

真實範例：

// 你有 3 個工具：WebSearch, GitHub, Database

// 傳統方式：寫出所有組合
async function workflow1() {
  const web = await WebSearch();
  const github = await GitHub();
  return process(web, github);
}

async function workflow2() {
  const web = await WebSearch();
  const db = await Database();
  return process(web, db);
}

async function workflow3() {
  const github = await GitHub();
  const db = await Database();
  return process(github, db);
}

// ... 還有更多（3! = 6 種組合）

1.2 Skills 的解決方案

意圖 → Skill 智能聚合 → 結果
         ↓
    [Tool A, Tool B, Tool C]
    自動選擇、執行、組合

改變了什麼：

✅ 不需要手動選擇工具
✅ 動態執行順序
✅ N 個工具只需 1 個 Skill
✅ 靈活組合

第二部分：從你熟悉的開始（Claude Code Skills）

2.1 一個簡單的研究 Skill

---
name: tech-research
description: 研究技術主題
triggers:
  - "研究"
  - "study"
tools:
  - WebSearch
  - WebFetch
  - Read
  - Write
---

## 執行步驟

1. 在網路上搜尋 [主題]
2. 閱讀前 5 筆結果
3. 提取關鍵資訊
4. 生成摘要報告
5. 儲存到檔案

這已經在解決 N*N 問題了！ 怎麼做到的？

// 你不需要寫這些：
async function searchOnly() { /* ... */ }
async function searchAndFetch() { /* ... */ }
async function searchFetchAndWrite() { /* ... */ }
// ... （很多組合）

// Skill 動態處理所有組合：
// - 有時只搜尋
// - 有時搜尋 + 讀取
// - 有時搜尋 + 讀取 + 寫入
// 根據需求自動決定！

2.2 理解三個核心角色

角色 1：工具聚合器

Skills 組合現有工具，不重新實作：

<!-- ✅ 好：使用現有工具 -->
tools:
  - WebSearch
  - GitHub
  - Database

<!-- ❌ 差：嘗試重新實作 -->
tools: []
# 然後從頭實作搜尋邏輯

角色 2：決策引擎

用 AI 決策替代人類判斷：

傳統方式：
[資料] → [人類決定：用 WebSearch] → [人類決定：用 GitHub] → [結果]

Skill：
[資料] → [AI 決定：WebSearch + GitHub] → [結果]

角色 3：執行協調器

自動處理複雜工作流：

## 執行步驟

1. **資料收集**
   - 搜尋網路（如果需要）
   - 查詢 GitHub（如果需要）
   - 檢查資料庫（如果需要）

2. **處理**
   - 提取相關資訊
   - 交叉參照來源

3. **輸出**
   - 生成報告
   - 儲存到檔案

第三部分：N*N 問題解釋

3.1 組合爆炸

3 個工具：A, B, C

可能的執行順序：
A → B → C
A → C → B
B → A → C
B → C → A
C → A → B
C → B → A

總共：3! = 6 種組合

加入條件執行（每個步驟可能需要/不需要）：

變成：2^3 × 3! = 48 種

3.2 真實世界的影響

// 真實專案有 10+ 工具
const tools = [
  'webSearch', 'github', 'database', 'api',
  'fileSystem', 'email', 'slack', 'jira',
  'analytics', 'monitor'
];

// 可能的組合：10! ≈ 3,628,800 種
// 不可能手動實作所有組合！

傳統方式：

開發時間：數年（360 萬種組合）
維護：不可能

Skill 方式：

開發時間：數天（10 個工具 + 1 個路由器）
維護：簡單（宣告式）
覆蓋：所有可能的組合

第四部分：實用 Skill 設計

4.1 單一職責原則

好的設計：

<!-- ✅ 每個 Skill 專注一個領域 -->
skills/
├── research-skill/      # 資料收集
├── writing-skill/       # 內容生成
├── publishing-skill/    # 發布管理
└── analytics-skill/     # 數據分析

不好的設計：

<!-- ❌ 一個 Skill 做所有事 -->
skills/
└── everything-skill/    # 負擔過重，難以維護

4.2 可組合性原則

N*N 解決方案：

// 傳統：實作所有組合
workflows/
├── research-to-writing/     # 研究→寫作
├── research-to-publishing/  # 研究→發布
├── writing-to-publishing/   # 寫作→發布
└── ... (N! 種組合)

// Skill：智能路由
skills/
├── orchestrator-skill/  # 動態決定調用順序
└── atomic-skills/       # 個別 skills
    ├── research/
    ├── writing/
    └── publishing/

4.3 真實範例：技術研究 Skill

場景：研究 OpenClaw 框架

搜尋相關文章
查詢 GitHub 數據
分析社群討論
生成綜合報告

傳統實作（偽代碼）：

// 你需要寫這些：
async function researchOpenClaw() {
  const web = await webSearch("OpenClaw");
  const github = await githubQuery("openclaw/openclaw");
  return combine(web, github);
}

async function researchVue() {
  const web = await webSearch("Vue.js");
  const github = await githubQuery("vuejs/core");
  return combine(web, github);
}

// ... 每個技術都重複

Skill 實作：

---
name: tech-research
description: 研究任何技術主題
tools:
  - WebSearch
  - WebFetch
  - Grep
---

## 執行步驟

1. **搜尋**
   - 搜尋 "[主題] tutorial 2026"
   - 搜尋 "[主題] documentation"

2. **GitHub 分析**
   - 查詢 [主題]/[主題] 倉庫
   - 提取 stars、forks、語言

3. **社群**
   - 檢查最近討論
   - 識別熱門議題

4. **報告**
   - 結合所有發現
   - 生成結構化報告

使用方式：

# 一個 Skill 處理任何技術
claude -p "研究 OpenClaw"
claude -p "研究 Vue.js"
claude -p "研究 React Query"

第五部分：從 Claude Code Skills 到 Agent SDK

5.1 概念轉移

你已經會寫 Claude Code Skills。現在將這個概念應用到 Agent SDK：

Claude Code Skill（你已知的）：

---
name: github-analyzer
description: 分析 GitHub 倉庫
tools: [WebSearch, WebFetch]
---

Agent SDK Skill（相同概念，不同平台）：

from anthropic import Anthropic

skill = {
    "name": "github-analyzer",
    "description": "分析 GitHub 倉庫",
    "tools": ["web_search", "web_fetch"],
    "instructions": """
    你是 GitHub 分析師。
    使用 web_search 和 web_fetch 來分析倉庫。
    """
}

agent = Anthropic()
result = agent.messages.create(
    model="claude-sonnet-4-20250514",
    system=skill["instructions"],
    tools=skill["tools"],
    messages=[{"role": "user", "content": "分析 openclaw/openclaw"}]
)

關鍵洞察：設計邏輯完全相同！只是語法不同。

5.2 跨平台 Skills

寫一次，到處執行：

---
name: repo-analyzer
description: 分析代碼倉庫
tools:
  - WebSearch    # Claude Code
  - web_search   # Agent SDK
  - web:search   # OpenClaw
---

## 通用執行流程

1. 檢測倉庫平台（GitHub/GitLab/Bitbucket）
2. 獲取倉庫元數據
3. 分析代碼結構
4. 生成報告

相同邏輯，不同平台：

// Claude Code：直接創建文件
.claude/skills/repo-analyzer/SKILL.md

// Agent SDK：用 Python 載入
loader = SkillLoader()
skill = loader.load(".claude/skills/repo-analyzer/SKILL.md")
agent = skill.to_agent_sdk()

// OpenClaw：用 TypeScript 載入
const skill = loader.load(".claude/skills/repo-analyzer/SKILL.md")
const openclawSkill = skill.to_openclaw()

第六部分：最佳實踐

6.1 設計檢查清單

## Skill 設計評估

### 功能性
- [ ] 明確的單一職責
- [ ] 清晰的輸入輸出定義
- [ ] 可測試的邏輯
- [ ] 錯誤處理機制

### 可組合性
- [ ] 標準化接口
- [ ] 獨立的工具依賴
- [ ] 可序列化的狀態
- [ ] 版本兼容性

### 可觀測性
- [ ] 完整的日誌
- [ ] 性能指標
- [ ] 錯誤追蹤
- [ ] 執行統計

### 可維護性
- [ ] 清晰的文檔
- [ ] 代碼註釋
- [ ] 測試覆蓋
- [ ] 示例代碼

6.2 性能優化

並行執行：

// ❌ 串行（慢）
for (const tool of tools) {
  await tool.execute();
}

// ✅ 並行（快）
await Promise.all(
  tools.map(tool => tool.execute())
);

快取策略：

class CachedSkill {
  private cache = new LRUCache<string, any>({
    max: 100,
    ttl: 1000 * 60 * 5  // 5 分鐘
  });

  async execute(input: any): Promise<any> {
    const key = this.generateKey(input);

    const cached = this.cache.get(key);
    if (cached) return cached;

    const result = await this.doExecute(input);
    this.cache.set(key, result);

    return result;
  }
}

第七部分：真實範例

範例 1：文檔處理器 Skill

使用場景：處理各種文檔類型

---
name: document-processor
description: 處理 PDF、Word、Markdown 文件
tools:
  - Read
  - Bash
  - WebFetch
---

## 執行步驟

1. **檢測格式**
   - 檢查副檔名
   - 驗證 MIME 類型

2. **提取內容**
   - PDF：使用 pdf-parser
   - Word：使用 pandoc
   - Markdown：直接讀取

3. **處理**
   - 提取文本
   - 識別結構
   - 解析元數據

4. **輸出**
   - 生成摘要
   - 儲存到 JSON/資料庫

處理 N 格式 × M 操作 = N×M 種組合

// 傳統：寫出每個組合
async function pdfToJson() { /* ... */ }
async function pdfToSummary() { /* ... */ }
async function wordToJson() { /* ... */ }
async function wordToSummary() { /* ... */ }
// ... （N×M 個實作）

// Skill：一個定義處理所有

範例 2：客服支援 Skill

使用場景：智能客服聚合

---
name: customer-support
description: 聚合多個知識來源
tools:
  - knowledge-base
  - faq-search
  - github-issues
  - slack-history
---

## 執行流程

1. **分類查詢**
   - 技術問題 → knowledge-base + github-issues
   - 帳單問題 → faq-search + crm
   - 帳戶問題 → slack-history + user-db

2. **選擇工具**
   - 根據分類動態選擇

3. **檢索與整合**
   - 查詢選定的來源
   - 結合結果
   - 生成答案

4. **回應**
   - 格式化答案
   - 包含來源引用

解決：4 個來源 × 3 種查詢類型 × 2 種回應格式 = 24 種組合

傳統：24 個獨立工作流 Skill：1 個宣告式定義

第八部分：進階模式

8.1 編排器模式

---
name: workflow-orchestrator
description: 協調多個 Skills
tools:
  - research-skill
  - writing-skill
  - publishing-skill
---

## 動態工作流

1. **解析意圖**
   - 用戶想發布文章
   → 需要：research + writing + publishing

   - 用戶只想研究
   → 需要：research

2. **執行選定的 Skills**
   - 按依賴順序執行
   - 在 skills 之間傳遞上下文

3. **聚合結果**
   - 組合輸出
   - 返回最終結果

8.2 後備模式

---
name: resilient-fetcher
description: 帶多個後備的獲取器
tools:
  - WebFetch
  - WebSearch
  - Read
---

## 執行策略

1. **主要**：優先嘗試 WebFetch
2. **後備 1**：失敗則用 WebSearch
3. **後備 2**：用 Read 檢查本地快取
4. **錯誤**：所有方法都失敗

總結：核心要點

核心概念

從 Claude Code Skills 開始
- 你已經會了
- 簡單、宣告式、有效
理解 N*N 問題
- 傳統：N! 種組合
- Skills：N 個工具 + 1 個路由器
- 節省：指數級成本降低
AI Skills 的三重角色
- 工具聚合器（組合現有能力）
- 決策引擎（替代人類判斷）
- 執行協調器（優化工作流）
跨平台應用
- 相同的設計邏輯
- 不同的語法
- 寫一次，到處執行

行動建議

初學者：

寫你的第一個 Claude Code Skill
識別重複性任務
設計智能路由
測試並迭代

進階開發者：

將 Skills 應用到 Agent SDK
建構編排器 Skills
實作快取與優化
與社群分享

好處

✅ 縮短開發時間：數天而非數年 ✅ 降低維護成本：宣告式勝過程序式 ✅ 靈活性：動態處理任何組合 ✅ 可擴展性：輕鬆添加新工具