eric861129/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)

• 問題：使用 web_fetch 獲取內容後，因流程中斷或遺漏步驟而未執行 write_file，導致本地出現空資料夾。
• 對策：每抓取一個檔案，應立即執行對應的寫入指令，並在完成後使用 ls -R 或 dir /s 驗證檔案是否確實存在於磁碟。

4. 清單未包含深層檔案 (Manifest Sync)

• 問題：skills-manifest.json 可能未掃描到過深層級的檔案，導致前端顯示異常。
• 對策：完成檔案寫入後，務必執行 npm run prebuild 觸發 generate-manifest.js 重新掃描，並隨機抽查 json 內容。

5. 遺漏配置文件 (Missing skill.json)

• 問題：部分 Repo（如 claude-starter）將自動啟用的元數據放在 skill.json 中，若未抓取會導致技能功能不完整。
• 對策：導入時必須同時抓取同目錄下的 skill.json。核心原則：使用者透過此平台下載的 SKILL 必須是完全體，嚴禁出現功能缺失或檔案不全的狀況。

6. 誤判技能路徑 (Skill Path Misidentification)

• 問題：習慣性尋找 skills/ 資料夾，而忽略了有些 Repo 本身就是一個單一技能。
• 對策：若根目錄存在 SKILL.md，應優先判斷該 Repo 是否為單一技能專案。在此情況下，抓取根目錄下的所有相關檔案（如 references/, scripts/ 等）進行導入。

7. 分類不一致 (Category Inconsistency)

• 問題：新增技能時使用了未在系統定義的分類名稱，導致前端顯示異常或型別錯誤。
• 對策：所有分類必須對齊 @src/types/skill.ts 中的 SkillCategory。若需新增分類，必須先修改該型別定義檔案。

---

💡 技巧：如何有效獲取 GitHub 內容

• 使用 web_fetch 抓取目錄清單時，請觀察檔案結構。
• 如果是大型 Repo，優先尋找 README.md 中提到的技能目錄。
• 確保抓取原始內容 (Raw Content) 以避免 HTML 標籤干擾。