5 Best Practices for Building AI Agent Skills

AI 智能體技能看似簡單——本質上就是放在資料夾裡的 Markdown 文件——但因為簡單，所以容易出錯。講者分享了建立可靠技能的五個核心實踐。

首先是描述的重要性。每個 skill.md 都以 YAML 頭部開始，定義名稱和描述。在大規模部署中（如安裝 100 項技能），代理無法同時載入所有技能內容，否則會充滿上下文窗口。因此代理啟動時只讀取每項技能的名稱和描述，這決定了技能是否會被調用。比如將合規技能簡單描述為「產生報告」太籠統，應改為「根據內部數據產生月度合規報告，當有人要求合規報告或月度申報時執行」。講者強調描述應稍微誇大一點，因為模型往往觸發不足，小看一點反而更安全。

其次，技能內容必須來自真正的領域專業知識。很多人會直接讓 AI 生成技能描述，結果是空泛廢話。正確做法是手動完成一遍任務並記錄實際有效的方法，或從現有數據綜合分析（舊報告、運行記錄、PR 回饋等）。講者引述英國同行 Simon Willison 的觀點：「保留領域專業知識，讓代理處理日常事務」。每次手動修正代理錯誤，那次修正都該被記下來，否則下週還得重複同樣的修正。講者舉例，某份月度合規報告在首次運行時出現行總數不符的問題，這類錯誤正是為什麼需要記錄陷阱和邊界情況。

第三個實踐是明智地利用上下文。當代理選擇一項技能時，才會真正讀取其主體內容，此時該技能的每一行都在與上下文窗口中其他信息爭奪模型注意力。建議將 skill.md 主體控制在 500 行或約 5000 字符內——只寫代理自己無法知道的信息，即模型訓練數據中尚未包含的內容。超大技能應拆分，將輔助信息放在 `references` 子資料夾，代理只在實際需要時才打開這些文件。

第四個實踐是使用確定性腳本。對於鬆散的步驟，寫說明讓模型發揮沒問題，因為通往正確答案的路有很多。但對於每次都必須完全正確的步驟，不要讓模型動態重新生成邏輯。此時應在技能資料夾中建立 `scripts` 目錄，放入腳本（如 script1），技能主體只需告訴代理「執行這個腳本」。腳本不會載入上下文，既節省令牌又更可靠。講者的例子中，合規報告原本用模型計算數字，後來改用確定性數學腳本，這類計算漏洞完全消失了。答案不是寫更多測試——測試只能發現已知要檢查的東西——而是對必須正確的部分，直接用邏輯替代猜測。

最後是安全審查。技能可以執行代碼、存取本地文件系統甚至 API 金鑰，這正是它們強大的原因，但也帶來風險。一份審計報告掃描近 4000 個公開技能，發現超過 35% 存在某種安全漏洞，13% 存在嚴重問題如提示注入或惡意軟體。必須像對待其他軟體依賴一樣審查代理技能——在使用前閱讀功能、檢查調用了哪些資源。開放標準無法保證個別技能安全。