quiz

name	quiz
description	Deliver interactive practice quizzes from study material.

Quiz

Convert AI-generated JSON quiz into NotebookLM-style interactive quiz interface. Multiple choice questions with immediate feedback, hints, completion statistics, and review mode.

What This Skill Does

Input: JSON file with quiz questions (generated by AI) Output: NotebookLM-style interactive HTML

This is a pure frontend converter - AI (Claude/Gemini) generates the quiz as JSON, this skill renders it with NotebookLM's exact UI/UX.

Output Contract

• Produces a single HTML quiz with scoring, feedback, and review mode.
• Output file is browser-ready and does not require additional assets.

Workflow

1. User: "Claude, generate a 15-question quiz about biology"
2. Claude: Generates JSON with questions, options, correct answers, explanations
3. Save JSON to file (e.g., biology_quiz.json)
4. Run from `skills/quiz`: `python main.py -i biology_quiz.json -o biology_quiz.html`
5. Open HTML → NotebookLM-style quiz interface

JSON Input Format

Option A: Simple Array

[
  {
    "question": "What is the powerhouse of the cell?",
    "options": [
      "Nucleus",
      "Mitochondria",
      "Ribosome",
      "Golgi apparatus"
    ],
    "correctIndex": 1,
    "hint": "It's responsible for energy production",
    "correctExplanation": "Mitochondria are the powerhouses of the cell, generating ATP through cellular respiration.",
    "wrongExplanation": "The answer is mitochondria - they produce energy in the form of ATP."
  }
]

Option B: With Title

{
  "title": "Biology Quiz",
  "questions": [
    {
      "question": "What is photosynthesis?",
      "options": [
        "Breaking down glucose",
        "Converting light to chemical energy",
        "Cell division",
        "Protein synthesis"
      ],
      "correctIndex": 1,
      "hint": "It involves sunlight and chlorophyll",
      "correctExplanation": "Photosynthesis converts light energy into chemical energy stored in glucose.",
      "wrongExplanation": "Photosynthesis is the process plants use to convert sunlight into energy."
    }
  ]
}

Usage

cd skills/quiz
python main.py --input quiz.json --output quiz.html

Parameters:

• --input, -i: Input JSON file (required)
• --output, -o: Output HTML file (default: quiz.html)

Math (KaTeX)

Use LaTeX delimiters in questions, options, hints, or explanations to render formulas:

$\frac{a}{b}$ inline, or $$\int_0^1 x^2\,dx$$ block

Notes:

• Inline math uses $...$ and block math uses $$...$$.
• Escape literal dollar signs as \$ to avoid math parsing.
• When local KaTeX assets are available, a fonts/ folder is created next to the HTML for offline rendering.

NotebookLM-Style Features

Visual Design

• Purple gradient background (same as NotebookLM)
• White quiz container with rounded corners and shadow
• Progress bar with gradient fill
• Color-coded feedback:
  • Green for correct answers (#22c55e)
  • Red for wrong answers (#ef4444)
  • Purple for selected options (#667eea)

Quiz Flow

1. Taking the Quiz

Action	Behavior
Click option (A/B/C/D)	Select answer and show immediate feedback
Click "Hint" button	Toggle hint visibility
Click "Previous"	Go to previous question
Click "Next"	Go to next question (only after answering)
Click "Finish Quiz"	Show completion statistics

2. Answer Feedback

• Correct Answer: Green checkmark (✓), "That's right!" message, explanation
• Wrong Answer: Red cross (✗), "Not quite" message, explanation + correct answer shown in green

3. Completion Screen

Shows comprehensive statistics:

• Score: 4/15 (correct/total)
• Accuracy: 27% (correct/answered)
• Right: Number of correct answers
• Wrong: Number of incorrect answers
• Skipped: Number of unanswered questions

4. Review Mode

• Click "Review Quiz" to navigate through all answers
• See which answers were correct/wrong
• "Finish Review" button on last question returns to completion screen

5. Retake

• Click "Retake Quiz" to start fresh
• All answers cleared
• Returns to first question

UI Elements

• Header: Quiz title + "Based on 1 source"
• Progress bar: Visual progress indicator
• Progress text: "5 / 15" format
• Option labels: A, B, C, D in circular badges
• Hint panel: Yellow background with lightbulb icon
• Navigation: Previous/Next buttons with disabled states
• Completion: 🎉 emoji, stats grid, action buttons

Features Comparison

Feature	This Skill	NotebookLM
Multiple choice (A/B/C/D)	✅	✅
Immediate feedback	✅	✅
Hints	✅	✅
Progress tracking	✅	✅
Completion statistics	✅	✅
Review mode	✅	✅
Retake quiz	✅	✅
Purple gradient	✅	✅
Vertical layout	✅	✅

Technical Details

• No LLM/AI: Pure JSON → HTML conversion
• No API Keys: No external calls
• Standalone HTML: All CSS/JS embedded
• Offline: Works without internet
• State Management: JavaScript for tracking answers and progress
• Responsive: Adapts to different screen sizes

Dependencies

pip install -r requirements.txt

Only requires: loguru (logging)

Integration with AI

Asking Claude

"Generate a 20-question quiz about [topic] in JSON format.
Use this structure:
[
  {
    "question": "...",
    "options": ["A", "B", "C", "D"],
    "correctIndex": 1,
    "hint": "optional hint",
    "correctExplanation": "why this is right",
    "wrongExplanation": "what to know if wrong"
  }
]
"

Asking Gemini

Same prompt works across any AI model that can generate structured JSON.

JSON Field Reference

Required Fields

• question (string): The question text
• options (array): Array of 4 answer choices
• correctIndex (number): Index of correct answer (0-3)

Optional Fields

• hint (string): Hint text to help with the question
• correctExplanation (string): Explanation shown when user answers correctly
• wrongExplanation (string): Explanation shown when user answers incorrectly
• explanation (string): Fallback explanation if correctExplanation/wrongExplanation not provided

Example Workflow

1. Generate quiz with Claude:

User: "Create a 15-question quiz about quantum physics"
Claude: Generates JSON and saves to quantum_quiz.json

2. Convert to interactive HTML:

cd skills/quiz
python main.py -i quantum_quiz.json -o quantum_quiz.html

3. Take the quiz:

• Open quantum_quiz.html in browser
• Answer questions with immediate feedback
• Use hints when needed
• View completion statistics
• Review answers
• Retake if desired

Tips

• Question quality: Each question should test one concept
• Options: Make distractors plausible but clearly wrong
• Explanations: Provide clear, educational feedback
• Hints: Give helpful clues without revealing the answer
• Quiz length: 10-20 questions is optimal for engagement
• Difficulty: Mix easy, medium, and hard questions

Customization

Want to change the colors? Edit main.py line 55:

background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);

Want different option letters? Edit line 491:

const letter = String.fromCharCode(65 + index); // A, B, C, D