wen aidev

Agent Skills 開發概念指南

底層邏輯與設計規範：寫出能與 AI Agent 穩定協作的自動化技能

什麼是 Agent Skills？

Skills 是 AI Agent（如 Claude Code、Roo Code 等）的擴充能力——它讓 AI 不只能回答問題，還能執行特定腳本、存取特定檔案，甚至串接你的內部 API 來完成複雜任務。

一個 Skill 本質上是一個放在 .claude/skills/ 資料夾裡的 SKILL.md 文件，加上可選的輔助腳本或文件。

💡 為什麼需要寫 Skills？

  • 統一認知：團隊共享相同的代碼規範或驗證規則，不需要每次 Prompt 重複講。
  • 自動化複雜流程：例如自動抓取 Jira Ticket、讀取 PR Diff 然後產生 Release Note。
  • 控制執行環境：讓 AI 呼叫你寫好的、經過測試的 Python / Bash 腳本，而不是自己憑空生成語法。

Skill 的基本結構

.claude/skills/
├── processing-invoices/
│   ├── SKILL.md        ← 主要指令（必須）
│   ├── extract.py      ← 執行腳本（選用）
│   └── REFERENCE.md    ← 詳細 API 規格（按需載入）

核心原則：漸進式揭露 (Progressive Disclosure)

Context Window（上下文視窗）是有限的運算資源，每次對話都在消耗它。最常見的錯誤是把所有說明都塞進 SKILL.md——這會讓 Claude 在還沒開始工作時就消耗大量 Token。

Progressive Disclosure 架構圖

圖說：優良的 Skill 架構，僅載入觸發的指令，並按需執行外部文件與腳本。

實踐三原則

1. 控制主文件大小

嚴格限制 SKILL.md 小於 500 行。只保留「Claude 完成任務所需的最低知識」。

2. 分離次要資訊

完整的 API 清單、範例資料等放入 REFERENCE.md，在 SKILL.md 中只留指向它的引用。

3. 不要解釋常識

不需要在 SKILL.md 裡解釋「什麼是 JSON」或「什麼是 REST」，Claude 預設就懂，解釋只是在浪費 Token。

發現性 (Discoverability)：命名與描述

Claude 的調度系統（Orchestrator）完全依賴 name 和 description 來判斷「現在這個任務該呼叫哪個 Skill」。命名精準，Skill 才能被正確觸發。

1. 用動名詞 (Gerund) 命名

用具體的動作行為命名，避免通用名詞。Claude 看到 'processing-invoices' 比看到 'tools' 更能理解這個 Skill 的用途。

1. 用動名詞 (Gerund) 命名

✅ 動名詞，精確描述這個 Skill 的行為

name: processing-invoices name: testing-code name: managing-databases

2. 第三人稱 + 觸發語境

描述要用第三人稱。更關鍵的是：在描述中明確告訴 Claude「什麼情況下」該用這個 Skill，讓調度更精準。

2. 第三人稱 + 觸發語境

✅ 第三人稱，包含 Use when

description: "Analyzes Excel spreadsheets and creates charts. Use when working with .xlsx files or data analysis tasks."

腳本穩健性：Solve，don't punt

當 Skill 包含可執行的腳本（Python、Bash 等）時，腳本 Crash 的代價極高——Claude 需要重新解讀錯誤訊息、嘗試修復，浪費大量 Token 與往返次數。

原則：在腳本端就處理錯誤，給 Claude 一個清晰的成功 / 失敗狀態，而不是拋出 Exception 讓它自己想辦法。

Solve, don't punt 錯誤處理對比圖

圖說：左側腳本 Crash 中斷工作流；右側腳本攔截錯誤並給予清晰的 Fallback，讓 Claude 能繼續完成任務。

腳本設計的三個規範

1. 魔術數字必須有語境註解

腳本中所有「神秘數字」要解釋原因，否則 Claude 無法在需要時幫你動態調整。

# ❌ Claude 不知道為什麼是 30，無法判斷是否該調整
TIMEOUT = 30

# ✅ Claude 知道背景，可以根據任務需求建議修改
# Maximum wait time for API response.
# Set to 30s based on observed P99 latency of upstream service.
TIMEOUT = 30

2. 防止 Path Traversal 攻擊

如果你的 Skill 接受 user input 作為路徑參數，必須嚴格驗證路徑範圍，防止惡意輸入（如 ../../etc/passwd）跳出允許的目錄。

import os

ALLOWED_BASE = "/workspace/project"

def safe_read(user_path: str) -> str:
    # Resolve to absolute path, preventing ../.. traversal
    abs_path = os.path.realpath(
        os.path.join(ALLOWED_BASE, user_path)
    )
    # Verify the resolved path is still within allowed base
    if not abs_path.startswith(ALLOWED_BASE):
        raise PermissionError(
            f"Access denied: path outside allowed directory"
        )
    with open(abs_path, "r") as f:
        return f.read()

3. 跨平台路徑一致性

即使你的腳本只在 Windows 上跑，也要統一使用 forward slashes（/），因為 Claude 的環境可能是 Linux / macOS，混用 \\ 會造成不可預期的問題。

# ❌ 在非 Windows 環境会 fail
path = "C:\Users\project\data.csv"

# ✅ 跨平台安全
import os
path = os.path.join("project", "data.csv")
# 或直接用 forward slash
path = "project/data.csv"

進階：Workflow 與反饋迴圈 (Feedback Loops)

對於需要多個步驟的複雜任務，光靠一段說明不夠——Claude 很可能在中途迷失、跳步驟，或遇到驗證失敗時不知道該怎麼辦。

解法是設計明確的 Workflow：用 Checklist 追蹤進度，並用顯式反饋迴圈定義「失敗時回到哪一步」。

📝 Checklist 範本：帶反饋迴圈的 Research Workflow

## Research synthesis workflow
Copy this checklist at the start and track progress:
```
Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations
```

**Step 1: Read all source documents**
Review each document in the sources/ directory.

**Step 3: Cross-reference claims**
For each major claim, verify it appears in ≥2 sources.

**Step 5: Verify citations**  ← 反饋迴圈在這裡
Check that every claim has a correct citation.
→ If citations are incomplete, return to Step 3.
→ Do NOT proceed to final output until all citations pass.

注意 Step 5 的 Feedback Loop：明確定義「驗證失敗時回到哪一步」，讓 Claude 知道失敗不是結束，而是要循環直到通過。

🔒 安全進階：Feedback Loop 在驗證場景的應用

Feedback Loop 的核心邏輯：在 Workflow 中指定「退出條件」和「重試條件」，防止 Claude 跳過驗證步驟直接輸出結果。

**Validation loop (must pass before proceeding)**:
1. Run test suite: python -m pytest tests/
   → Exit code 0: proceed to Step 5
   → Exit code != 0: fix failures, re-run from this step
   → Do NOT skip this validation under any circumstances

2. Check code coverage ≥ 80%:
   → If coverage < 80%: add tests, re-run from Step 4
   → Only proceed when BOTH conditions pass

* Feedback Loop 的重點是「退出條件要量化」（exit code 0、coverage ≥ 80%），模糊的「確認沒問題」很容易被 Claude 忽略。

掌握基礎後，繼續學習五大 Workflow 設計模式與完整的 Troubleshooting 指南

進入進階篇 →