---
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
```json
[
  {
    "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
```json
{
  "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

```bash
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:

```text
$\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

```bash
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**:
```bash
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:
```python
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
```

Want different option letters? Edit line 491:
```python
const letter = String.fromCharCode(65 + index); // A, B, C, D
```