validate-skills

Validate Skills

驗證 skills/ 中的所有技能是否符合 agentskills.io 規範與 Claude Code 最佳實踐。

驗證檢查清單

針對每個技能目錄，檢查以下項目：

規範遵循 (agentskills.io)

檢查項目	規則
name 格式	1-64 字元，小寫字母數字與連字號，無前導/結尾/連續連字號
name 與目錄相符	目錄名稱必須等於 name 欄位
description 長度	1-1024 字元，不可為空
選用欄位有效	若有 license、metadata、compatibility 則需有效

最佳實踐 (Claude Code)

檢查項目	規則
描述格式	第三人稱，描述「做什麼」與「何時使用」
主體長度	少於 500 行
載入深度為一層	SKILL.md 是唯一的漸進式揭露進入點：每個參考檔案必須可從 SKILL.md 到達。參考檔案之間可以互相交叉連結以利導覽（請參閱下方備註）。
連結為 Markdown	使用 [text](path) 而非裸檔名
無冗餘	不要在正文中重複描述
簡潔	只加入 Claude 尚未擁有的上下文

一層深度 vs. 交叉連結。 一層深度規則針對的是漸進式揭露載入鏈——一個只能透過先載入另一個參考才能發現的參考（SKILL.md → a.md → b.md，其中 b.md 未從 SKILL.md 連結）。這是缺陷：它會對載入器隱藏內容。

它不禁止導覽用交叉連結。根據 AGENTS.md，參考檔案結尾應有「相關技能」頁尾連結同層參考，這是必要的。只要兩個端點也都能直接從 SKILL.md 到達，交叉連結就沒問題。只有當某個參考只能透過另一個參考到達時才需標記。

執行方式

1. 找出所有技能目錄：

   fd -t d -d 1 . skills/
   

2. 針對每個技能，讀取 SKILL.md 並根據上述規則檢查

3. 以下列格式回報問題：

   ## 驗證結果
   
   ### skills/example-skill
   - [通過] name 格式有效
   - [失敗] name "example" 與目錄 "example-skill" 不符
   - [通過] description 長度正確 (156 字元)
   

參考資料

• agentskills.io 規範
• Claude Code 最佳實踐