撰寫技能
重複使用現有擁有者
在建立套件前，請先檢視現有的技能目錄。對於儲存庫工作，請在授權的工作區中搜尋目標目錄及所有相關的原始目錄。對於授權的即時函式庫工作，請使用 Rundesk 的目錄與技能列表；請勿為了繞過任務的存取邊界而開啟即時函式庫。在決定之前，請閱讀可能匹配項目的描述，然後閱讀其主體及相關參考資料。
當請求的功能與某個現有擁有者在使用者意圖、工作流程與權限上一致時，請擴展現有擁有者。在該處新增支援腳本、參考資料或測試，而不是建立第二個路由表面。僅在該功能需要不同的路由、判斷、權限或證明時，才建立新的技能；並記錄該差異，以避免僅因名稱相近而被視為正當理由。
選擇工件
- 技能是指令邊界：何時行動、應用何種判斷、遵循哪個程序，以及如何證明結果。
- 工作流程腳本是確定性機制，用於重複的本地轉換、驗證或編排。
- 整合新增了外部服務邊界：憑證、帳戶、網路故障、權限或遠端影響。
將一次性自動化保留在其專案中，並將單一代理的私有重複命令保留在該代理的腳本區域。僅在未來回合需要路由或判斷才能使用時，才將腳本封裝在技能中。請勿以代理必須重新解釋的散文來取代確定性程式碼。
在發布任何可重複使用的腳本之前，請閱讀可重複使用的工作流程腳本。當腳本使用憑證、設定檔、OAuth、網路或遠端影響時，也請閱讀外部服務整合。
安全放置
僅在授權進行即時建立或安裝時，才在 local 中建立私有技能。對於草稿、審查、儲存庫變更或隔離測試，請留在指定的工作區或暫存目錄中；請勿檢查或變更即時函式庫來找出結果可能最終放置的位置。
對於授權的私有技能，請向 Rundesk 請求函式庫，而不是從 RUNDESK_HOME 推導或嵌入絕對路徑。請取代範例名稱：
skill_name=release-notes
skill_library=$("$RUNDESK_COMMAND" skills | sed -n '1s/^skills in //p')
test -n "$skill_library" || exit 1
mkdir -p "$skill_library/local/$skill_name"
撰寫 <library>/local/<name>/SKILL.md，然後將其授予指定的代理：
"$RUNDESK_COMMAND" skills grant "$RUNDESK_AGENT" local/release-notes
該授予將在代理的下一個回合（而非當前回合）變為可發現。在為其他安裝建立技能之前，請閱讀發布技能目錄；發布的技能屬於目錄儲存庫，而非 local。
僅使用所需形狀
<name>/
├── SKILL.md 必要：路由與核心程序
├── rundesk.json 可選：必要的環境值
├── scripts/ 可選：可重複使用的命令
├── tests/ 可選：當目錄測試區域不擁有其所有權時的腳本合約
├── references/ 可選：條件式載入的詳細資訊
└── assets/ 可選：複製或輸出的材料
僅在有內容時才建立可選路徑。省略 README、更新日誌、安裝指南與建立歷史。
先撰寫路由
frontmatter 僅包含 name 和 description。
- 將
name與目錄名稱匹配。最多使用 64 個小寫字母、數字及單一連字號。 - 根據使用者意圖進行路由，包含可能未提及技能名稱的間接請求。以
Use when、Apply when或等效的適用性語言開頭；提示詞句並非觸發條件。 - 目標為兩個簡短的句子：適用性，然後是所提供的專門工作流程或知識。僅對可能接近的精確匹配項目新增
Do not use。僅包含身體載入前路由所需的概念。省略步驟、測試、效益聲明與實作細節；僅在檔案類型、工具或格式決定技能是否應觸發時才提及它們。 - 使用仍能正確路由的最短描述；1,024 個字元是上限，而非目標。將每個觸發條件都放在那裡，因為每個持有者每個回合都需要為其付出代價，且在路由成功之前身體是不可用的。
# 錯誤：嵌入了無法幫助路由的實作與驗證。
description: Use when creating release notes. It reads Git history, writes Markdown, groups commits, checks links, runs validation, and produces concise internal and public versions with accurate formatting.
# 正確：僅說明意圖、所提供的判斷以及最接近的邊界。
description: Use when preparing release notes from shipped repository changes. It supplies an audience-focused workflow grounded in verified history. Do not use for unreleased plans.
僅保留行為指引
以執行順序使用命令式步驟。假設讀者能夠推理、編輯並使用一般工具。僅在能改變執行、防止可能失敗或路由所需細節時，才保留一個句子。
- 將核心程序、一個強預設值以及不明顯的陷阱保留在
SKILL.md中。 - 對脆弱的操作使用精確命令；對多種方法都可行的情況使用簡潔的判斷。
- 解釋某個約束所要防止的失敗，而不是加入未說明的強調。
- 在介紹每個參考資料時，說明何時應閱讀它。保持單一事實來源；使用連結而非重述。
- 移除背景、處理歷史、過時的聲明以及已在別處載入的規則。
- 區分觀察到的合約與建議的預設值。追蹤技術約束的來源，並將真實的陷阱教導為症狀、原因、替代方案與可觀察的證明。
將 SKILL.md 保持在 500 行以下；將條件式詳細資訊移動一層到連結的參考資料中。
預算上下文
| 部分 | Token 成本 | 保留在該處 |
|---|---|---|
description | 每次回合 | 最短的完整觸發條件 |
SKILL.md | 路由之後 | 核心程序、預設值、陷阱 |
references/ | 閱讀時 | 條件式詳細資訊與較大範例 |
scripts/ | 輸出進入上下文 | 具有有限輸出的確定性工作 |
tests/ | 僅驗證 | 可執行的合約與邊緣案例 |
assets/ | 使用時 | 範本與輸出材料 |
偏好簡短的範例。限定腳本輸出為下一個決策所需的部分。
證明整個技能
-
驗證目錄名稱、frontmatter 名稱、描述語法與限制。
-
當需要授予時，套用該授予並驗證下一個回合：
"$RUNDESK_COMMAND" skills list "$RUNDESK_AGENT" "$RUNDESK_COMMAND" skills doctor "$RUNDESK_AGENT" -
執行每個腳本參考擁有的邊緣矩陣與直接可執行進入點。
-
在不同的全新回合中，嘗試直接請求、間接請求以及一個接近的精確誤判。確認身體與必要的參考資料在工作開始前載入；按類別修復路由，而非複製提示詞句。
-
對於一個重要的技能，將相同任務與沒有該技能的新的基線進行比較。然後讓一個單獨的測試代理在不具備預期實作的情況下使用它。直接審查工件與命令；代理的摘要並非證明。移除未帶來實質改善的指引。
-
將生成的書面內容與可執行正確性分開審查：路由精確性、執行順序、有用的判斷、簡潔性、重複性與參考紀律。綠色的腳本測試並不能證明書面內容的品質。驗證或觀察事實承諾；測試可執行的聲明並縮小部分真理。用一個對抗性的反例來挑戰語意聲明，該反例應在保留便捷聚合的同時，改變真實的關係或結果——變異檢查無法修復錯誤的測試預言機。審查整個介面，包括空成功、重複證據以及每個資料依賴的輸出區段。