teaching-minigames

Teaching Material Mini-Games Skill

Automatically convert teaching materials into a formative assessment webpage with "one mini-game per key point," including QR Codes so teachers can quickly use it on any digital platform.

Overall Workflow

1. 分析教材 → 2. 提取重點清單（確認） → 3. 製作小遊戲 HTML
→ 4. 打包索引頁 → 5. 自動上傳 GitHub → 6. 啟用 GitHub Pages
→ 7. 回傳每個遊戲的網址 + QR Code

Step 1: Analyze the teaching materials and extract key points

Read the teaching materials uploaded by the user (PDF / images / .docx / plain text). Use the following framework to extract "Key Learning Points":

Each key point = an independent, testable knowledge unit
Naming format:重點N：[簡短標題]
Suggested quantity: 3–10 (determined by the density of the teaching materials)
Each key point should include: core concept, 2–4 assessment materials (answers, distractors, example sentences, etc.)

Before continuing, first confirm with the user whether the list of key points is correct.

Step 2: Choose game types

Based on the nature of each key point, choose the most suitable one from the following game types:

Game Type	Applicable Scenario	Filename
Multiple Choice (MCQ)	Concept understanding, definitions	`game-mcq.html`
Fill-in-Blank	Keyword memory, formulas	`game-fill.html`
Matching Pairs	Vocabulary correspondence, cause-and-effect relationships	`game-match.html`
True/False	Clarifying common misconceptions	`game-tf.html`
Ordering	Steps, chronology, processes	`game-order.html`
Memory Cards	Vocabulary and image memory	`game-memory.html`

Each key point can use a different type to increase variety.

Step 3: Create the HTML for each mini-game

Each game must bea completely independent single HTML file, with no dependence on an external server.

HTML Structure Specifications

<!DOCTYPE html>
<html lang="zh-TW">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>[重點標題] - 小遊戲</title>
  <!-- 所有 CSS 內嵌於 <style> -->
</head>
<body>
  <!-- 遊戲內容 -->
  <!-- 所有 JS 內嵌於 <script> -->
</body>
</html>

Required UI Elements

Every game page must include:

Title: key point name
Instructions: brief game rules (1 sentence)
Game Area: interactive questions
Instant Feedback: when correct ✅ show encouragement, when wrong ❌ show the correct answer
Score/Progress Display: for example "2 / 4 questions"
Replay Button

Design Style Specifications

Mobile-first (mobile-friendly)
Font size ≥ 16px
Buttons large enough (min-height: 44px)
Use a high-contrast, clear educational color scheme
Do not use any external CDN (fully inline, works offline)

For detailed HTML templates for each game type, please refer to:references/game-templates.md

Step 4: Create the main index page

Generate a index.htmlas the entry point for all mini-games:

List all key points and the corresponding game links
Display a QR Code for each game (using the QR Code embedding method, see below)
Can be printed / projected for students to use

Step 5: QR Code Embedding (within HTML)

Embed code in each game's HTML that dynamically displays its own QR Code, allowing users to display the QR Code directly in the browser:

<div class="qr-section">
  <img id="qr-img" width="150" height="150" alt="QR Code">
  <p>掃描開啟此遊戲</p>
</div>
<script>
  // 發佈後自動顯示當前頁面的 QR Code
  document.getElementById('qr-img').src =
    'https://api.qrserver.com/v1/create-qr-code/?size=150x150&data='
    + encodeURIComponent(window.location.href);
</script>

Step 6: Automatically upload to GitHub and publish

For complete instructions, please refer to:references/github-publish.md

6-1. Collect necessary information

First ask the user (if not provided):

GitHub Personal Access Token(requires repo permission)
GitHub account name
Repository name(default:teaching-games, will be created automatically if it does not exist)

6-2. Run the upload script

Use bash_tool to call the GitHub REST API with a Python script:

python3 /home/claude/github_upload.py \
  --token "$TOKEN" \
  --user "$GITHUB_USER" \
  --repo "$REPO_NAME" \
  --files-dir "/mnt/user-data/outputs/"

For detailed script content, see references/github-publish.md 's "Complete Upload Script (Python Version)".

Claude should write this script to /home/claude/github_upload.py。

6-3. Enable GitHub Pages

After the upload is complete, automatically call the Pages API to enable publishing.

6-4. Wait and confirm

GitHub Pages takes about 1-3 minutesto go live. Claude should inform the user of the expected wait time.

Step 7: Final output

7-1. Output files

Claude should output the following files to /mnt/user-data/outputs/, and use present_files to present them:

outputs/
├── index.html              # 總索引頁（含所有 QR Code）
├── game-01-[重點名].html
├── game-02-[重點名].html
└── ...

7-2. Return URLs and QR Codes in the conversation

After successful publishing,in the conversation messagedisplay each game's information in Markdown format:

## ✅ 已發佈至 GitHub Pages！

> ⏳ 若連結顯示 404，請等待 1～3 分鐘後重試。

---

### 📋 總索引頁
🔗 https://[user].github.io/[repo]/
![QR](https://api.qrserver.com/v1/create-qr-code/?size=200x200&data=https://[user].github.io/[repo]/)

---

### 重點 1：[標題]（選擇題）
🔗 https://[user].github.io/[repo]/game-01-xxx.html
![QR](https://api.qrserver.com/v1/create-qr-code/?size=180x180&data=https://[user].github.io/[repo]/game-01-xxx.html)

### 重點 2：[標題]（配對題）
🔗 ...
![QR](...)

Quality Checklist

Before finishing each game, confirm:

HTML syntax is correct and can be opened directly in a browser
All questions and answers come from the teaching materials, no hallucinations
Each game has at least 3 questions (4-6 questions recommended)
When an answer is wrong, display the correct answer and explanation
The game displays properly on mobile phones
QR Code uses window.location.href(dynamic, automatically correct after publishing)
The index page lists all games

After uploading and publishing, confirm:

GitHub Repo has been created (or already exists)
All HTML files have been successfully uploaded
GitHub Pages has been enabled
Each game's URL and QR Code image are displayed in the conversation
Inform the user that it will take effect in 1-3 minutes

Notes

Do not use external JS/CSS CDNs: Ensure offline availability (school networks often have restrictions)
Language: The game interface language follows the teaching material language (Chinese teaching materials -> Chinese games)
Question accuracy: All questions and answers must faithfully come from the teaching materials; do not make them up
Difficulty: Focus on formative assessment, moderate difficulty, emphasizing memory and comprehension levels (Bloom's Level 1-2)