JMBargueno/skanvil

skanvil 是做什麼的？

目標

透過 skanvil CLI 變更技能庫，使技能資料夾、SKILL.md frontmatter、README 索引和庫慣例保持一致，並維持驗證通過。

何時啟用此技能

• 儲存庫包含 .skanvilrc.json、包含 SKILL.md 檔案的 skills/ 資料夾，或在 package.json 中有 skanvil 相依性。
• 使用者要求新增、撰寫、重新命名、移動、重新命名、重新描述、刪除、列出、驗證或索引技能。
• skanvil validate、npm test 或 CI 因 skanvil 診斷而失敗。
• 使用者希望將某個庫的技能提供給另一個專案中的 Claude Code、GitHub Copilot 或 Codex 使用。

指示

1. 熟悉環境

1. 閱讀 .skanvilrc.json。它定義了分類（id、資料夾 prefix、README title、aliases）、必填章節、佔位符和規則嚴重程度。若檔案遺失，則表示使用預設預設值：front-、back-、無前綴的 transversal（預設）和 _internal。
2. 執行 npx skanvil list --json 以查看每個技能及其分類、README 存在狀態和有效性。
3. 在進行任何變更前先執行 npx skanvil validate --json，以便了解哪些問題已存在。

2. 黃金規則

• 絕對不要手動重新命名、移動或刪除技能資料夾，也絕對不要手動編輯 README 索引。 請使用 skanvil edit，它會同步保持資料夾、frontmatter name、# 標題 和 README 條目一致，並在失敗時回滾。
• 絕對不要手動建立技能資料夾。 請使用 skanvil add，它會套用分類前綴、範本、frontmatter 元數據和 README 條目。
• 在非互動式 shell 中，務必傳遞所有選項。 add 需要 --type、--name 和 --description。edit --remove 需要 --yes。否則指令會提示輸入，或若無 TTY 則會失敗。
• 絕對不要不帶引數執行 skanvil 或執行 skanvil wizard。 它們會開啟為人類設計的互動式選單。請使用下方明確的指令。如果使用者偏好選單，建議他們自行執行 npx skanvil。
• 每當需要解析輸出時，加上 --json。資料會輸出到 stdout；警告和錯誤則輸出到 stderr。
• 每次變更後執行 npx skanvil validate，並確保以零錯誤結束。退出碼 1 表示錯誤，或在使用 --strict 時表示警告。
• 每個指令前面加上 npx，除非 skanvil 已在 PATH 中。使用 -C <路徑> 來指定另一個資料夾中的庫。

3. 常見任務

建立一個技能，然後撰寫其內容。

npx skanvil add --type <分類> --name "<簡短名稱>" \
  --description "<它的功能>。當 <觸發情境> 時使用。"

然後編輯 skills/<前綴><名稱>/SKILL.md：

• 每個必填章節都要填寫具體、可操作的內容。
• 替換所有通用的範本句子。在你完成之前，validate 會報告 template-unchanged 警告，而 validate --strict（庫的 npm test）會失敗。
• 將冗長的內容移至 references/，並且只連結到存在的檔案（broken-references）。

當那些資料夾會保持空時，使用 --no-scripts、--no-assets 或 --no-references。使用 --template <名稱> 來指定 .skanvil/templates/ 中的自訂範本。

重新命名或移動一個技能。

npx skanvil edit <技能> --rename <新名稱>          # 前綴會自動重新套用
npx skanvil edit <技能> --type <其他分類>          # 新前綴、README 區段、元數據
npx skanvil edit <技能> --title "<標題>" --description "<文字>"

--rename 接受基礎名稱：edit front-a --rename b 會產生 front-b。

刪除一個技能。 先與使用者確認；此操作不可恢復。

npx skanvil edit <技能> --remove --yes

修復驗證錯誤。

1. 執行 npx skanvil doctor --fix。它會修復 README 條目、name 不匹配、frontmatter 中的製表符，並將 tools 轉換為 allowed-tools。
2. 透過編輯 SKILL.md 來修復其餘問題。請使用下方的診斷表。
3. 再次執行 npx skanvil validate。

在 .skanvilrc.json 中變更分類標題後重建 README 索引：

npx skanvil index          # 重寫索引區段
npx skanvil index --check  # 僅驗證（CI）

將技能安裝到一個專案中。

npx skanvil sync <專案目錄> -C <庫目錄> --target claude,copilot --dry-run   # 預覽
npx skanvil sync <專案目錄> -C <庫目錄> --target claude,copilot
npx skanvil sync --from @scope/package --target agents                             # 已安裝的套件

目標：

• claude 安裝到 .claude/skills；
• copilot 安裝到 .github/skills；
• agents 和 codex 安裝到 .agents/skills。
• 自訂路徑必須是專案內的一個資料夾。
• --global（不帶專案目錄）改為安裝到使用者的 ~/.claude/skills、~/.copilot/skills 或 ~/.agents/skills。僅在使用者要求技能在所有專案中都可用時使用。

sync 的行為：

• 它絕不會覆寫非其安裝的資料夾。
• 它會修剪已從庫中移除的技能。
• 除非給予 --force，否則它會跳過有驗證錯誤的技能。
• 它絕不會發布 _internal 技能。

新增或變更分類。 編輯 .skanvilrc.json 中的 categories：

• 恰好一個分類有 "default": true 且無前綴；
• 其他每個分類都有一個前綴，該前綴是 _ 或結尾為 - 的 kebab-case；
• 沒有任何前綴可以以另一個前綴開頭。

然後使用 edit --type 移動現有技能，並執行 skanvil index。

4. 撰寫良好的技能內容

• description 說明技能的功能以及何時使用，包含代理會看到的觸發關鍵字。長度不得超過 1024 個字元。
• name 等於資料夾名稱：小寫字母、數字和單一連字號，長度最多 64 個字元。
• 主體： 保持 SKILL.md 在 500 行以內。將指示撰寫為編號、可驗證的步驟，並將範例、邊緣案例和長檢查清單放在 references/ 中（一層深度）。
• 佔位符： 絕對不要留下填充文字。任何 validation.placeholders 條目（待辦事項標記、虛擬拉丁文文字、「待決定」備註）都會導致驗證失敗。
• metadata： 僅限字串值，因此需為數字加上引號，例如 version: "1.0"。
• allowed-tools： 一個空格分隔的字串，而非列表。

5. 診斷 → 修復

規則	修復方式
readme-missing, readme-orphan, readme-section	npx skanvil doctor --fix
name-matches-folder, name-required	doctor --fix，或如果資料夾名稱錯誤則使用 edit --rename
frontmatter-tabs, tools-field	doctor --fix
frontmatter	修復 --- 行之間的 YAML（為包含 : 或 # 的值加上引號）。
required-sections	新增 validation.requiredSections 中列出的遺失 ## 區段。
placeholders	將佔位符文字替換為真實內容。
description-length, max-lines	縮短；將細節移至 references/。
metadata-format	為非字串值加上引號。
duplicate-name	兩個資料夾共享一個 name：使用 edit --rename 重新命名其中一個。
broken-references	建立被參照的檔案，或修正連結（路徑相對於技能）。
template-unchanged	將通用的模板句子改寫為特定技能的指示。

請參閱 references/REFERENCE.md 以了解每個指令選項、設定架構和 JSON 輸出格式。

輸出格式

向使用者報告：

• 您執行的 skanvil 指令；
• 已建立、變更或移除的技能及其資料夾名稱；
• 最終的 skanvil validate 結果（錯誤和警告），以及任何留待他們決定的項目。

品質標準

• 每個結構性變更都經過 skanvil add 或 skanvil edit。沒有手動進行的資料夾重新命名或 README 索引編輯。
• npx skanvil validate 報告無錯誤，且 npx skanvil index --check 通過。
• 新建或編輯的技能具有包含觸發條件的具體描述，且無模板填充文字或佔位符。
• 刪除和同步到其他專案的操作已獲得使用者確認。