github-skill-importer

Github Skill Importer (從 GitHub 導入技能 SOP)

此技能定義了如何從外部 GitHub Repository 尋找、驗證並抓取 AI 技能，將其導入至 SKILLS_All-in-one 平台的標準作業流程。

🔍 第一階段：搜尋與定位 (Discovery)

當使用者提供一個 GitHub URL 時，請執行以下步驟：

1. 進入技能根目錄：在 Repo 中尋找名為 skills/ 或 .claude/skills/ (或其他可能的技能存放路徑) 的資料夾。
2. 辨識 Repo 型態：
   • 多技能型：若存在 skills/ 等資料夾，每個子資料夾代表一個獨立技能。
   • 單一技能型：若 Repo 根目錄直接包含 SKILL.md 且無 skills/ 資料夾，則將整個 Repo 視為一個完整技能。
3. 定位目標：根據使用者的需求或 Repo 型態，定位到正確的技能目錄。

✅ 第二階段：格式驗證 (Validation)

在導入之前，必須確認該目錄符合 「正確的技能形式」：

1. 必要檔案：目錄內必須包含 SKILL.md。
2. 元數據檢查：SKILL.md 的頂部必須包含 YAML Frontmatter，例如：

   ---
   name: skill-name
   description: brief description
   ---
   

3. 結構檢查：檢查是否有 references/、scripts/ 或 examples/ 等輔助資料夾，這些也應一併導入。

📥 第三階段：下載與存放 (Import)

1. 建立暫存區：在 @public\SKILLS\Uncategorized\ 下建立與 Repo 中相同的資料夾名稱。
2. 抓取檔案：使用 web_fetch 讀取並使用 write_file 寫入所有相關檔案。
   • 路徑：@public\SKILLS\Uncategorized\{FolderName}\SKILL.md
   • 路徑：@public\SKILLS\Uncategorized\{FolderName}\references\** (若有)

🛠️ 第四階段：銜接上架流程 (Onboarding)

完成導入後，請立即切換至 Skill Onboarding Guide (技能上架 SOP) 執行後續動作：

1. 分類 (Classification)：
   • 優先從 @src/types/skill.ts 中的 SkillCategory 選擇最合適的現有分類。
   • 嚴禁隨意建立新分類。只有在現有分類完全不適用時，才應在 @src/types/skill.ts 中新增定義後再使用。
2. 資料庫同步：更新 database/init_skills.sql。
3. 前端同步：更新 src/data/skills.ts。
4. 清單同步：執行 npm run prebuild 更新 skills-manifest.json。

---

⚠️ 常見問題與教訓 (Lessons Learned)

在執行導入任務時，請務必注意以下曾發生的錯誤，以確保資料完整性：

1. 遺漏深層子目錄 (Missing Subdirectories)

• 問題：僅抓取根目錄的 SKILL.md，忽略了 references/、scripts/ 或 services/ 等關鍵參考資料。
• 對策：在定位技能後，必須遞迴掃描該目錄下的所有子資料夾。若 SKILL.md 中有提到其他檔案連結，需優先補齊。

2. 中文編碼損壞 (Encoding Corruption)

• 問題：在 Windows 環境下使用 PowerShell 的 Set-Content 或 > 重導向符號處理包含中文的檔案時，會導致編碼轉為 ANSI/UTF-16，使繁體中文變成亂碼 (?)。
• 對策：嚴禁使用 PowerShell 原生命令修改檔案內容。請統一使用 write_file 工具或 Node.js 腳本並明確指定 utf8 編碼寫入。

3. 抓取後未寫入 (Silent Write Failure)