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

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

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