Tw Kahoot Skill — Development skill for Claude Code

tw-kahoot-skill 使用手冊

Kahoot 教學資源 Skill。它把具來源追溯、受測者與命題藍圖的測驗 JSON 轉為 `.xlsx`、`.quality.json`、`.readiness.json`，並提供試算表與 PowerPoint／Google 簡報／Keynote／PDF 匯入草稿的教師操作指南。

事前條件

• Node.js 18 以上；在此資料夾執行 npm install。
• 可定位的教學來源（教材名稱及頁碼、段落等 locator）。
• 明確受測者：年級、程度、教學語言、至少一項先備能力。
• 學習目標、測驗用途、題數與命題藍圖。請從 assessment-brief.example.json 複製後擴充。

標準使用

npm install
node scripts/build-xlsx.mjs quiz.json out.xlsx

成功時會產出：

檔案	先看什麼
out.xlsx	交由教師匯入的試算表。
out.quality.json	status 必須是 ready；看 blockers、warnings、perQuestion 與 blueprint。
out.readiness.json	看每題是否 ready/skipped，以及截斷、媒體與時間等格式提醒。

輸入與命題品質

最上層為 Quiz（`title`、`questions[]`）；必須有 `assessment.version: 1`。`assessment` 必含：

• sources[]: 每筆 id、title、locator。
• audience: gradeLevel、proficiency、language、非空的 prerequisites[]。
• objectives[]: 每筆 id、text，以及 purpose。
• blueprint[]: objectiveId、cognitiveLevel、difficulty、正整數 count。

每題必含 `sourceRefIds[]`、`objectiveIds[]`、`cognitiveLevel`、`difficulty`。認知層次只能是 `remember`、`understand`、`apply`、`analyze`、`evaluate`、`create`；難度只能是 `basic`、`developing`、`proficient`、`advanced`。藍圖總題數和每個「目標 × 層次 × 難度」格都要與實際題目一致。選擇題至少有一個正解，`multiple_choice` 剛好一個；建議每題寫 `explanation` 供教師複核。

缺任一必填資料、追溯失敗、答案鍵錯誤或藍圖不符時，CLI 會以 `assessment-quality-blocked` 停止，**不會產出 xlsx**。這是刻意的安全門檻，不要在期限壓力下跳過。

Kahoot 匯入

此工具只映射 `multiple_choice`、`multiple_select`、`true_false`。每題至少兩個、最多四個選項；題幹最多 120 字、選項最多 75 字；時間會調整至 5/10/20/30/60/90/120/240 秒。媒體與不支援題型必須在 Kahoot 編輯器手動補建；完整轉述 stdout 的 warnings。

教師操作：Kahoot → Create → Add question → Import → Import spreadsheet → 先下載當日官方 template 比對 → 上傳 `out.xlsx` → 在未發布草稿中逐題預覽與修正 → 再由教師決定是否發布。`readiness.json` 會保留目前欄位是以仍在線的 2019 年官方範本為基礎的提醒；它不是對當日平台 UI 的保證。

簡報教材轉換

已登入後可由 `建立新內容 → 建立新 Kahoot → 匯入投影片` 上傳 PowerPoint、Google 簡報、Keynote 或 PDF；也可選 Google Drive／OneDrive。頁面顯示檔案上限 80