Community寫作與編輯github.com

撰寫代理技能

設計、起草、修改或審查可重複使用的 AI 代理技能與 SKILL.md 指令套件。適用於建立或改進技能的範圍、觸發描述、工作流程、支援參考或腳本、安全邊界與評估;使技能適應主機代理與實際任務。

撰寫代理技能 是什麼?

此技能旨在幫助開發者或 AI 代理使用者建立、修改或審查結構化且可執行的代理技能指令套件(SKILL.md)。它提供了一個完整的指南,從定義技能契約開始,包括觸發條件、輸入要求、允許權限與輸出定義。接著引導使用者撰寫精簡的 SKILL.md 主體,避免冗長或互相衝突的規則,並建議將大型領域參考移至獨立的參考檔案。最後,強調測試與迭代的重要性,建議使用代表性的案例與邊界情況來驗證技能的正確性與安全性。此技能適用於任何支援自訂技能的 AI 代理平台,如 Claude Code、Cursor 或 Codex,幫助使用者交付可被代理可靠執行的工作套件,而不是僅提供計劃或批評。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/rafik-mikhail/write-agent-skill/tree/main

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

撰寫代理技能 是做什麼的?

目標

交付一個可由代理執行的指令套件,用於一個連貫且可重複使用的工作。將其建立在使用者的任務、範例、工具環境、現有工件與修正之上。如果沒有實際範例,請標示假設並起草最小的可測試指令,而不是發明產品特定的 API。完成並呈現實際要求的技能,而不僅僅是計劃、進度報告或批評。

定義契約

  1. 說明觸發條件:應啟動此技能的任務與輸入,以及不應啟動的相鄰請求。將 description 編寫為簡潔的路由規則,說明其用途與使用時機。
  2. 說明必要與可選的輸入、代理的允許權限、預期輸出以及完成的定義。解決與相鄰技能在交接點的重疊問題;不要僅僅因為主題相關而合併不同的階段。
  3. 標記哪些行為是強制的安全或正確性閘門、哪些是預設的啟發式規則、哪些是可選的增強功能。指令不能強制執行運行時權限:請使用平台控制來管理檔案系統、網路與工具存取。

起草 SKILL.md

使用 YAML 前置元數據,name 為小寫連字符形式且與其資料夾名稱匹配,並包含具體的 description。遵循主機平台的格式與功能;不要假設可選的元數據或 allowed-tools 能在所有平台上強制執行存取權限。

保持主體精簡:工作與邊界、輸入、決策程序、停止/失敗處理、輸出契約以及不明顯的陷阱。提供一條預設路徑,而不是一份同等的選項清單。對脆弱操作給出確切步驟;對上下文選擇中的合理判斷留有餘地。避免在每個章節重複相同的禁止事項,或將一次性任務的答案嵌入為通用程序。

將大型領域參考移至集中的 references/ 檔案,並確切告訴代理何時閱讀它們。僅在確認腳本的運行時依賴與驗證行為後,才為重複性的確定性工作添加可重複使用的腳本。確保參考文件可直接從 SKILL.md 到達,並且不要聲稱草稿已被安裝、執行或驗證,而實際情況並非如此。

測試與修改

從 2-3 個代表性案例開始,包括一個邊界案例;當技能處理不受信任的內容或具有重要邊界時,添加負面觸發與對抗性案例。在沒有技能、有技能或對比先前草稿的情況下運行全新會話。根據可觀察的輸出與工具行為進行評分,而不是根據指令聽起來多麼優美。檢查執行軌跡中不必要的步驟、遺漏的證據、錯誤觸發與範圍蔓延。對於機械性檢查使用程式碼;讓人工審查實質性判斷。移除那些增加成本但未能防止實際失敗的指令。

交付檢查

在回覆前,確認所要求的完整工件確實存在且內部一致。當使用者要求完整的 Markdown 時,交付整個當前的 SKILL.md,而不是修補片段。如果正在建立檔案,請確認它存在且包含完整的草稿;誠實報告未經測試的狀態。簡要說明哪些內容已更改以及剩餘的驗證需求。不要將對一個技能的要求轉變為不相關的套件,除非有明確請求。

相關技能