AI Agent Skills 設計原則

在開發 AI Agent 的過程中，撰寫穩定且高效的技能 (Skills) 是一項充滿挑戰的工作。無論你是在 ChatGPT 上開發 Custom GPTs，或是為 Claude 撰寫 Tool Use 機制，只要技能設計得不夠精確，Agent 就可能會誤用工具、產生幻覺，甚至在複雜的任務中陷入無窮迴圈。

為了確保系統的可靠性，業界歸納出了幾項核心的設計思維。

原子性設計與單一職責

設計技能時，最重要的原則就是保持工具的「原子性 (Atomic Scope)」。一個技能應該只負責解決一件事情，並且擁有清晰的邊界。

如果一個工具被設計成「包山包海」的萬能介面，例如一個叫做 manage_database 的工具同時負責讀取、寫入、刪除和備份，Agent 往往會不知道該如何正確組合參數，進而導致執行失敗或誤刪資料。

❌ 錯誤設計：龐大且模糊的工具

{
  "name": "data_tool",
  "description": "處理所有資料庫操作，包含查詢用戶、更新訂單和刪除記錄。"
}

✅ 正確設計：拆分為原子性工具 將其拆解成多個小而美的獨立技能，不僅能讓 Agent 更容易理解每個工具的用途，也能提升任務執行的成功率。

{
  "name": "get_user_profile",
  "description": "透過 User ID 查詢單一使用者的基本資料。"
}
// 另一個獨立的技能
{
  "name": "update_order_status",
  "description": "更新特定訂單的物流狀態。"
}

職責分離：判斷與執行的切分

在 AI 系統的架構中，必須清楚區分「語言模型」與「技能腳本」各自的職責。一般而言，Agent 負責「理解、推論與規劃」，而技能則負責「明確的執行與回報」。

這意味著我們不應該將所有邏輯都交給語言模型去猜測。當某項任務需要絕對的一致性與準確度時（例如：計算金融數據、檢查資料庫權限、或是發送重要的 API 請求），應該將這些規則寫死在後端的 API 或腳本中，成為一個確定性 (Deterministic) 的操作。

例如，與其讓 Claude 自己寫一段 Python 程式碼去計算複雜的稅率，不如提供一個 calculate_tax 的技能，讓 Claude 只要傳入「金額」，後端程式碼負責回傳精確的「稅額」。語言模型只需要決定「何時」呼叫，而不需要煩惱「如何」算。

提供預設值與收斂選項

當面對多種操作方式時，給予 AI 過多的選擇反而會造成困擾。如果一個技能提供了數十種可選參數，Agent 很有可能會隨機組合出不合理的請求。

在設計技能的介面時，建議只開放必要的參數，並為其他設定提供合理的預設值。如果某個選項只有在極少數極端情況下才會用到，請考慮將它隱藏，或是在技能的文字描述中明確告知 Agent 在什麼情況下才可以去修改這個預設值。

# 技能的後端實作範例：預設處理大部分情況，僅開放必要的輸入參數
def extract_text(file_path, use_ocr=False):
    """
    從文件中提取文字。預設使用一般文字解析。
    【給 Agent 的提示】：若檔案為圖片或純掃描的 PDF 檔，才需要將 use_ocr 設為 True。
    """
    if use_ocr:
        return perform_ocr(file_path)
    else:
        return parse_standard_text(file_path)

這樣的設計能有效限縮 Agent 的決策範圍，避免它在不需要的情境下浪費運算資源與等待時間。

清晰且針對性的工具描述 (Description)

無論是 ChatGPT 還是 Claude，語言模型都是透過閱讀「工具描述 (Description)」來決定是否要呼叫該技能。因此，描述的撰寫必須極度清晰且具有針對性。

一個優秀的描述不僅要說明「這個工具能做什麼」，更要強調「什麼時候該用它」。避免使用過度攏統的詞彙，而是應該加入具體的關鍵字與觸發情境。

❌ 錯誤描述

"處理 PDF 檔案。" (太過簡略，Agent 不知道能處理什麼)

✅ 正確描述

"從 PDF 文件中提取純文字內容。當使用者上傳 PDF 檔案，並要求「總結文章」、「尋找特定段落」或「翻譯內容」時，請先使用此技能獲取文本。" (清楚定義了功能以及觸發的對話情境)