撰寫代理技能 是做什麼的?
目標
交付一個可由代理執行的指令套件,用於一個連貫且可重複使用的工作。將其建立在使用者的任務、範例、工具環境、現有工件與修正之上。如果沒有實際範例,請標示假設並起草最小的可測試指令,而不是發明產品特定的 API。完成並呈現實際要求的技能,而不僅僅是計劃、進度報告或批評。
定義契約
- 說明觸發條件:應啟動此技能的任務與輸入,以及不應啟動的相鄰請求。將
description編寫為簡潔的路由規則,說明其用途與使用時機。 - 說明必要與可選的輸入、代理的允許權限、預期輸出以及完成的定義。解決與相鄰技能在交接點的重疊問題;不要僅僅因為主題相關而合併不同的階段。
- 標記哪些行為是強制的安全或正確性閘門、哪些是預設的啟發式規則、哪些是可選的增強功能。指令不能強制執行運行時權限:請使用平台控制來管理檔案系統、網路與工具存取。
起草 SKILL.md
使用 YAML 前置元數據,name 為小寫連字符形式且與其資料夾名稱匹配,並包含具體的 description。遵循主機平台的格式與功能;不要假設可選的元數據或 allowed-tools 能在所有平台上強制執行存取權限。
保持主體精簡:工作與邊界、輸入、決策程序、停止/失敗處理、輸出契約以及不明顯的陷阱。提供一條預設路徑,而不是一份同等的選項清單。對脆弱操作給出確切步驟;對上下文選擇中的合理判斷留有餘地。避免在每個章節重複相同的禁止事項,或將一次性任務的答案嵌入為通用程序。
將大型領域參考移至集中的 references/ 檔案,並確切告訴代理何時閱讀它們。僅在確認腳本的運行時依賴與驗證行為後,才為重複性的確定性工作添加可重複使用的腳本。確保參考文件可直接從 SKILL.md 到達,並且不要聲稱草稿已被安裝、執行或驗證,而實際情況並非如此。
測試與修改
從 2-3 個代表性案例開始,包括一個邊界案例;當技能處理不受信任的內容或具有重要邊界時,添加負面觸發與對抗性案例。在沒有技能、有技能或對比先前草稿的情況下運行全新會話。根據可觀察的輸出與工具行為進行評分,而不是根據指令聽起來多麼優美。檢查執行軌跡中不必要的步驟、遺漏的證據、錯誤觸發與範圍蔓延。對於機械性檢查使用程式碼;讓人工審查實質性判斷。移除那些增加成本但未能防止實際失敗的指令。
交付檢查
在回覆前,確認所要求的完整工件確實存在且內部一致。當使用者要求完整的 Markdown 時,交付整個當前的 SKILL.md,而不是修補片段。如果正在建立檔案,請確認它存在且包含完整的草稿;誠實報告未經測試的狀態。簡要說明哪些內容已更改以及剩餘的驗證需求。不要將對一個技能的要求轉變為不相關的套件,除非有明確請求。