quiz-generator

Files (7)

• SKILL.md
• redes-quiz-summary.md · examples/
• redes-quiz.html · examples/
• redes-quiz.yaml · examples/
• yaml-schema.md · references/
• yaml_to_html.py
• yaml_to_md.py

SKILL.md (first lines)

# Quiz Generator Skill

Generates structured multiple-choice study questions from a Markdown document and outputs
them as a YAML file ready to use in study tools, scripts, or Claude Code pipelines.

---

## Workflow

### 1. Read the source document

- Accept input as: uploaded `.md` file, pasted Markdown text, or a file path.
- Extract the main topics, concepts, definitions, processes, and facts.
- Identify natural groupings or sections to distribute questions evenly.

### 2. Analyse and plan questions

**Coverage is the priority.** Before writing any questions, do a full inventory of the document:

1. List every distinct concept, definition, fact, process, list, and relationship in the document.
2. Group them by section or topic.
3. Assign at least one question per distinct concept — do not merge or skip concepts to stay under a number limit.

**Question count rules:**
- Target **at least 2 questions per topic or concept or definition or fact or process** for a typical document.
- Full knowledge coverage always wins over a round number.
- Only generate fewer questions if the document genuinely does not contain enough material (e.g. a very short or narrow document).
- If the user specifies a number explicitly, treat it as a minimum floor, not a ceiling.

**Question type mapping:**
- Key **facts / definitions** → `single` answer
- Lists, characteristics, steps, or multi-part concepts → `multiple` answer
- Recommended split: ~40% single, ~60% multiple

**Difficulty distribution:**
- Aim for a balanced mix: ~30% easy, ~45% medium, ~25% hard
- Easy → recall / definitions
- Medium → comprehension / application
- Hard → analysis / edge cases / relationships between concepts

### 3. Generate the YAML output

Use the canonical schema below. Output **only valid YAML** — no prose before or after,
no markdown code fences, unless the user asks to see it in the chat.

```yaml
quiz:
  title: "Topic Name"           # derived from the document title or first heading
  source: "filename.md"         # original file name, or "pasted content" if no file
  generated_at: "YYYY-MM-DD"   # today's date

  questions:
    - id: 1
      question: "Question text here?"
      type: single              # single | multiple
      options:
        - id: a
          text: "Option A"
        - id: b
          text: "Option B"
        - id: c
          text: "Option C"
        - id: d
          text: "Option D"
      answers: [b]              # always a list, even for single-answer questions
      explanation: "Brief explanation of why these answers are correct."
      topic: "High-level subject grouping for this question."  # E.g. 'OSI Model', 'TCP/IP', 'Security', 'DNS'. Used to group or filter questions by topic.
      difficulty: medium        # easy | medium | hard
      tags: [tag1, tag2]        # 1-3 relevant topic tags from the document
```

### 4. Quality checks before outputting

**Coverage:**
- [ ] Every section of the document has at least one question
- [ ] No significant concept, definition, or fact from the document is left uncovered
- [ ] If concepts remain uncovered, add more questions until all are covered

**Question quality:**
- [ ] Every question has **at least 3 options** (4 preferred)
- [ ] `answers` list matches valid `option.id` values
- [ ] `type: multiple` questions have **2 or more correct answers**
- [ ] `type: single` questions have **exactly 1 correct answer**
- [ ] Explanations are concise (1-3 sentences) and educational
- [ ] No duplicate questions
- [ ] Tags are lowercase, no spaces (use hyphens if needed)

### 5. Save the YAML output file

- Default filename: `<source-basename>-quiz.yaml`  
  Example: `redes.md` → `redes-quiz.yaml`
- If running in Claude Code, save to the same directory as the source file unless told otherwise.
- If in Claude.ai chat, present the YAML in a code block for the user to copy.

### 6. Generate the HTML test file

After saving the YAML, run the conversion script to produce the interactive HTML test:

```bash
python3 skills/quiz-generator/yaml_to_html.py <source-basename>-quiz.yaml
```

This produces `<source-basename>-quiz.html` alongside the YAML. Do **not** generate the HTML manually — always delegate to `yaml_to_html.py`.

---

### 7. Generate the summary Markdown file

After saving the YAML, run the conversion script to produce the summary:

```bash
python3 skills/quiz-generator/yaml_to_md.py <source-basename>-quiz.yaml
```

This produces `<source-basename>-quiz-summary.md` alongside the YAML. Do **not** generate the summary manually — always delegate to `yaml_to_md.py`.

---

## Options the user can specify

From Emmerson-Miranda/claude-skills, MIT.

More from Emmerson-Miranda/claude-skills