
Quiz Generator
- 6 installs
- 2 repo stars
- Updated August 1, 2026
- vishalsachdev/claude-skills
Helps with ai & agent building tasks.
About
quiz-generator is a Claude Code skill for ai & agent building. It helps solo builders move faster with AI-assisted development.
- quiz-generator
- AI & Agent Building
- AI-coding skill
Quiz Generator by the numbers
- 6 all-time installs (skills.sh)
- +1 installs in the week ending Jul 27, 2026 (Skillselion tracking)
- Ranked #12,739 of 16,556 AI & Agent Building skills by installs in the Skillselion catalog
- Data as of Aug 2, 2026 (Skillselion catalog sync)
npx skills add https://github.com/vishalsachdev/claude-skills --skill quiz-generatorAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 6 |
|---|---|
| repo stars | ★ 2 |
| Last updated | August 1, 2026 |
| Repository | vishalsachdev/claude-skills ↗ |
What it does
Helps with ai & agent building tasks.
Files
Quiz Generator for Intelligent Textbooks
Version: 0.2
Overview
1. For each markdown chapter, generate interactive multiple-choice quizzes for textbook chapters with and quality distractor analysis. 2. Generate quality reports in markdown format. 3. Updated mkdocs.yml navigation to include quizzes and reports.
Purpose
This skill automates quiz creation for intelligent textbooks by analyzing chapter content to generate contextually relevant multiple-choice questions. Each quiz is aligned to specific concepts from the learning graph, distributed across Bloom's Taxonomy cognitive levels, and formatted using mkdocs-material question admonitions with upper-alpha (A, B, C, D) answer choices. The skill ensures quality distractors, balanced answer distribution, and comprehensive explanations for educational value.
When to Use This Skill
Use this skill after:
1. Chapter content has been generated or written (1000+ words per chapter) 2. Learning graph exists with concept dependencies 3. Glossary is available (recommended for terminology questions)
Trigger this skill when:
- Creating quizzes for new chapters
- Updating quizzes after content revisions
- Building comprehensive quiz bank for entire textbook
- Exporting quiz data for LMS or chatbot integration
The skill can run incrementally (chapter by chapter) or in batch mode (entire textbook).
Workflow
Step 1: Assess Content Readiness
Indicate to the user that the Quiz Generator Skill (version) is running.
Calculate content readiness score (1-100) for each target chapter:
Quality Checks:
1. Chapter word count:
- 2000+ words = excellent (20 pts)
- 1000-1999 words = good (15 pts)
- 500-999 words = basic (10 pts)
- <500 words = insufficient (5 pts)
2. Example coverage:
- 60%+ concepts with examples = excellent (20 pts)
- 40-59% = good (15 pts)
- 20-39% = basic (10 pts)
- <20% = insufficient (5 pts)
3. Glossary coverage:
- 80%+ chapter concepts defined = excellent (20 pts)
- 60-79% = good (15 pts)
- 40-59% = basic (10 pts)
- <40% = insufficient (5 pts)
4. Concept clarity:
- Clear explanations for all concepts (20 pts)
- Most concepts clear (15 pts)
- Some unclear concepts (10 pts)
- Many unclear concepts (5 pts)
5. Learning graph alignment:
- All chapter concepts mapped (20 pts)
- Most mapped (15 pts)
- Some mapped (10 pts)
- Few mapped (5 pts)
Content Readiness Ranges:
- 90-100: Rich content, excellent quiz quality possible
- 70-89: Good content, solid quiz possible
- 50-69: Basic content, limited quiz possible
- Below 50: Insufficient content for quality quiz
User Dialog Triggers:
- Score < 60: Ask "Chapter [X] has limited content ([N] words). Generate shorter quiz or skip?"
- No glossary: Ask "No glossary found. Definition questions will be limited. Proceed?"
- Concept gaps: Ask "[N] concepts in chapter not in learning graph. Continue with available concepts?"
- No learning outcomes: Ask "No Bloom's Taxonomy outcomes in course description. Use default distribution?"
Step 2: Determine Target Distribution
Based on chapter type (introductory, intermediate, advanced), set target Bloom's Taxonomy distribution:
Introductory Chapters:
- 40% Remember
- 40% Understand
- 15% Apply
- 5% Analyze
- 0% Evaluate
- 0% Create
Intermediate Chapters:
- 25% Remember
- 30% Understand
- 30% Apply
- 15% Analyze
- 0% Evaluate
- 0% Create
Advanced Chapters:
- 15% Remember
- 20% Understand
- 25% Apply
- 25% Analyze
- 10% Evaluate
- 5% Create
Determine chapter type by:
- Position in textbook (first 3 chapters = introductory)
- Concept centrality in learning graph (high centrality = advanced)
- Explicit markers in chapter metadata
- User specification
Target question count: 8-12 per chapter (default: 10)
Step 3: Identify Concepts to Test
Analyze chapter content and learning graph to prioritize concepts:
Priority 1 (Must Test):
- High-centrality concepts in learning graph
- Concepts mentioned in chapter title or introduction
- Concepts with dedicated sections
- Key terms emphasized in bold or glossary links
Priority 2 (Should Test):
- Supporting concepts with substantial explanation
- Concepts with examples
- Prerequisites reviewed in chapter
- Concepts from learning objectives
Priority 3 (May Test):
- Peripheral concepts mentioned briefly
- Related concepts for context
- Future topics previewed
Aim for 80%+ coverage of Priority 1 concepts.
Step 4: Generate Questions by Bloom's Level
For each concept selected for testing, generate question at appropriate Bloom's level following target distribution.
IMPORTANT FORMATTING REQUIREMENT:
All questions MUST use the mkdocs-material question admonition format with upper-alpha list styling:
#### 1. What is the primary purpose of a learning graph?
<div class="upper-alpha" markdown>
1. To create visual decorations for textbooks
2. To map prerequisite relationships between concepts
3. To generate random quiz questions
4. To organize files in a directory structure
</div>
??? question "Show Answer"
The correct answer is **B**. A learning graph is a directed graph that maps prerequisite relationships between concepts, showing which concepts must be learned before others. This ensures proper scaffolding in educational content.
**Concept Tested:** Learning Graph
**See:** [Learning Graph Concept](../concepts/learning-graph.md)Formatting Rules:
1. Use level-4 header (####) with question number 2. Write question as complete sentence ending with ? 3. Use <div class="upper-alpha" markdown> wrapper 4. Write 4 answer options as numbered list (1, 2, 3, 4) 5. Use ??? question "Show Answer" admonition 6. Indent answer content with 4 spaces 7. Start with "The correct answer is [LETTER]." 8. Include concept name and link to source 9. Maintain blank line before and after div
Question Writing Guidelines:
Remember Level:
- Ask for definitions from glossary
- Test fact recall
- Identify terminology
- Example: "What is the definition of [concept]?"
Understand Level:
- Ask for explanations
- Test comprehension of relationships
- Compare/contrast concepts
- Example: "Which best describes the relationship between [A] and [B]?"
Apply Level:
- Present scenarios requiring concept application
- Test problem-solving using learned methods
- Example: "Given [scenario], which approach would you use?"
Analyze Level:
- Ask to identify patterns or causes
- Test ability to break down concepts
- Example: "What is the underlying reason for [phenomenon]?"
Evaluate Level:
- Ask for judgments based on criteria
- Test critical thinking
- Example: "Which approach would be most effective for [goal]?"
Create Level:
- Ask to design solutions
- Test synthesis of concepts
- Example: "How would you design a [system] that [requirements]?"
Step 5: Write Quality Distractors
For each incorrect answer option (distractors), ensure:
Plausibility:
- Sounds reasonable to someone who hasn't learned the material
- Uses related terminology
- Avoids obviously wrong answers
- Similar length to correct answer
Educational Value:
- Addresses common misconceptions
- Tests understanding of related concepts
- Discriminates between levels of knowledge
- Not trick questions or word games
Common Distractor Patterns:
- Partial truth (correct in different context)
- Reversal (opposite of correct answer)
- Similar terminology (related but distinct concept)
- Common error (typical student mistake)
Avoid:
- "All of the above" or "None of the above"
- Jokes or nonsensical options
- Grammatically inconsistent options
- Answers that overlap or both could be correct
Step 6: Write Explanations
For each question, write explanation that:
Confirms Correct Answer:
- State clearly: "The correct answer is [LETTER]."
- Explain why this answer is correct
- Reference chapter content or concept definition
- Target: 50-100 words
Teaches (Optional but Recommended):
- Briefly explain why distractors are incorrect
- Clarify common misconceptions
- Provide additional context
- Link to chapter section for more detail
Example Explanation:
The correct answer is **B**. A learning graph is a directed graph that maps
prerequisite relationships between concepts. Option A is incorrect because
learning graphs serve a structural purpose, not decorative. Option C is
incorrect because quiz generation is not the primary purpose. Option D
confuses learning graphs with file systems.
**Concept Tested:** Learning Graph
**See:** [Learning Graph Concept](../concepts/learning-graph.md#definition)Step 7: Ensure Answer Balance
Check that correct answers are distributed evenly across A, B, C, D:
Target Distribution:
- A: 25% (±5%)
- B: 25% (±5%)
- C: 25% (±5%)
- D: 25% (±5%)
Avoid Patterns:
- All C's in a row
- Alternating A-B-A-B
- Predictable sequences
- Position bias (first/last always correct)
Randomization Strategy:
- Generate random sequence before writing quiz
- Shuffle for each question
- Verify distribution after completion
- Adjust if imbalanced
Step 8: Create Quiz File
Generate quiz file with proper structure:
Option 1: Separate Quiz File (docs/[section]/[chapter-name]-quiz.md):
# Quiz: [Chapter Name]
Test your understanding of [chapter topic] with these questions.
---
#### 1. [Question text]?
<div class="upper-alpha" markdown>
1. [Option 1]
2. [Option 2]
3. [Option 3]
4. [Option 4]
</div>
??? question "Show Answer"
The correct answer is **[LETTER]**. [Explanation]
**Concept Tested:** [Concept Name]
**See:** [Link to chapter section]
---
#### 2. [Question text]?
[Continue for all questions...]Option 2: Embedded in Chapter (append to chapter file):
[Chapter content...]
---
## Chapter Quiz
Test your understanding with these review questions.
#### 1. [Question text]?
[Continue with quiz questions...]Formatting Requirements:
- Use horizontal rules (---) between questions
- Number questions sequentially (1, 2, 3...)
- Maintain consistent spacing
- Ensure all markdown renders correctly
Step 9: Generate Metadata File
Create docs/learning-graph/quizzes/[chapter-name]-quiz-metadata.json:
{
"chapter": "Chapter Name",
"chapter_file": "docs/section/chapter-name.md",
"quiz_file": "docs/section/chapter-name-quiz.md",
"generated_date": "YYYY-MM-DD",
"total_questions": 10,
"content_readiness_score": 85,
"overall_quality_score": 78,
"questions": [
{
"id": "ch1-q001",
"number": 1,
"question_text": "What is the primary purpose of a learning graph?",
"correct_answer": "B",
"bloom_level": "Understand",
"difficulty": "medium",
"concept_tested": "Learning Graph",
"source_link": "../concepts/learning-graph.md",
"distractor_quality": 0.85,
"explanation_word_count": 67
}
],
"answer_distribution": {
"A": 2,
"B": 3,
"C": 3,
"D": 2
},
"bloom_distribution": {
"Remember": 2,
"Understand": 4,
"Apply": 3,
"Analyze": 1,
"Evaluate": 0,
"Create": 0
},
"concept_coverage": {
"total_concepts": 12,
"tested_concepts": 10,
"coverage_percentage": 83
}
}Step 10: Generate Quiz Bank (Aggregate)
Create or update docs/learning-graph/quiz-bank.json with all questions:
{
"textbook_title": "Building Intelligent Textbooks",
"generated_date": "YYYY-MM-DD",
"total_chapters": 20,
"total_questions": 187,
"questions": [
{
"id": "ch1-q001",
"chapter": "Introduction to Learning Graphs",
"question_text": "What is the primary purpose of a learning graph?",
"options": {
"A": "To create visual decorations for textbooks",
"B": "To map prerequisite relationships between concepts",
"C": "To generate random quiz questions",
"D": "To organize files in a directory structure"
},
"correct_answer": "B",
"explanation": "A learning graph is a directed graph...",
"bloom_level": "Understand",
"difficulty": "medium",
"concept": "Learning Graph",
"chapter_file": "docs/concepts/learning-graph.md",
"source_section": "#definition",
"tags": ["graph", "prerequisites", "scaffolding"]
}
]
}Use Cases for Quiz Bank:
- LMS export (Moodle, Canvas, Blackboard XML)
- Quiz randomization (select subset)
- Alternative quiz versions
- Chatbot integration (practice questions)
- Study app integration
Step 11: Generate Quality Report
Create docs/learning-graph/quiz-generation-report.md:
# Quiz Generation Quality Report
Generated: YYYY-MM-DD
## Overall Statistics
- **Total Chapters:** 20
- **Total Questions:** 187
- **Avg Questions per Chapter:** 9.4
- **Overall Quality Score:** 76/100
## Per-Chapter Summary
| Chapter | Questions | Quality Score | Bloom's Score | Coverage |
|---------|-----------|---------------|---------------|----------|
| Ch 1: Introduction | 10 | 82/100 | 24/25 | 83% |
| Ch 2: Learning Graphs | 12 | 78/100 | 22/25 | 90% |
| ... | ... | ... | ... | ... |
## Bloom's Taxonomy Distribution (Overall)
| Level | Actual | Target | Deviation |
|-------|--------|--------|-----------|
| Remember | 22% | 25% | -3% ✓ |
| Understand | 28% | 30% | -2% ✓ |
| Apply | 27% | 25% | +2% ✓ |
| Analyze | 18% | 15% | +3% ✓ |
| Evaluate | 4% | 4% | 0% ✓ |
| Create | 1% | 1% | 0% ✓ |
**Bloom's Distribution Score:** 24/25 (excellent)
## Answer Balance (Overall)
- A: 24% (45/187)
- B: 26% (49/187)
- C: 25% (47/187)
- D: 25% (46/187)
**Answer Balance Score:** 15/15 (perfect distribution)
## Concept Coverage
- **Total Concepts:** 198
- **Tested Concepts:** 156
- **Coverage:** 79%
**Coverage Score:** 16/20 (good)
## Question Quality Analysis
- **Well-formed questions:** 92% (172/187)
- **Quality distractors:** 88% avg
- **Clear explanations:** 100%
- **Valid links:** 98%
**Question Quality Score:** 28/30 (excellent)
## Recommendations
### High Priority
1. Increase coverage for 15 untested high-centrality concepts
2. Add 2-3 more Remember-level questions (+3%)
3. Fix 3 questions with ambiguous phrasing
### Medium Priority
1. Improve distractors for 12 questions (quality < 80%)
2. Add more Apply-level questions for Ch 5, 8, 12
3. Verify and update 3 broken links
### Low Priority
1. Add alternative questions for popular concepts
2. Create study guide versions
3. Export to LMS-compatible formats
## Gaps by Chapter
**Chapters with low coverage (<70%):**
- Ch 7: Advanced Concepts (64% coverage) - Missing questions for: [list]
- Ch 14: Integration Patterns (58% coverage) - Missing questions for: [list]Step 12: Validate Quality
Perform comprehensive validation:
1. No Ambiguity:
- Each question has exactly one defensible correct answer
- Question stem is clear and complete
- No grammatical errors
2. Distractor Quality:
- All wrong answers are plausible
- Distractors test understanding, not just guessing
- Similar length and grammatical structure
- No overlapping answers
3. Grammar & Clarity:
- Professional writing throughout
- Consistent verb tense
- Proper punctuation
- No typos
4. Answer Balance:
- Correct answers distributed across A, B, C, D
- Within 20-30% per option (target: 25%)
- No predictable patterns
5. Bloom's Distribution:
- Matches target for chapter type
- Within ±15% acceptable
- Progressive difficulty through quiz
6. Concept Coverage:
- 75%+ of major concepts tested
- Important concepts have multiple questions
- No over-testing trivial concepts
7. No Duplicates:
- Unique questions across all quizzes
- No near-duplicates (>80% similar)
8. Explanation Quality:
- All questions have explanations
- Explanations teach, not just confirm
- 50-100 words target
- Reference chapter sections
9. Link Validation:
- All source links point to existing content
- Use section anchors where appropriate
- Links render correctly
10. Bias Check:
- No cultural bias
- No gender bias
- No assumptions about background
- Accessible language
Success Criteria:
- Overall quality score > 70/100
- 8-12 questions per chapter
- Bloom's distribution within ±15% of target
- 75%+ concept coverage
- Answer balance within 20-30% per option
- 100% questions have explanations
- No duplicate questions
- All links valid
Step 13: Generate Alternative Questions (Optional)
Create docs/learning-graph/quizzes/alternative-questions.json with 2-3 alternative questions per concept:
{
"alternatives": [
{
"concept": "Learning Graph",
"questions": [
{
"question_text": "Which data structure is used to represent a learning graph?",
"options": {
"A": "Linked list",
"B": "Directed acyclic graph",
"C": "Binary tree",
"D": "Hash table"
},
"correct_answer": "B",
"bloom_level": "Remember"
},
{
"question_text": "What problem does a learning graph solve?",
"options": {
"A": "Organizing files alphabetically",
"B": "Determining concept learning order",
"C": "Generating quiz questions",
"D": "Creating visual diagrams"
},
"correct_answer": "B",
"bloom_level": "Understand"
}
]
}
]
}Use for:
- Quiz randomization
- Test variations (A/B versions)
- Practice mode (different questions each time)
- Adaptive difficulty
Question Format Reference
Complete Example with All Elements
#### 3. Given a course with 50 concepts, what is the most important factor in organizing the learning graph?
<div class="upper-alpha" markdown>
1. Alphabetical order of concept names
2. Prerequisite relationships between concepts
3. The length of concept definitions
4. The visual appearance of the graph diagram
</div>
??? question "Show Answer"
The correct answer is **B**. Prerequisite relationships are the most important factor because they determine the order in which concepts must be learned. A learning graph maps these dependencies to ensure students learn foundational concepts before advanced ones. Alphabetical order (A) and visual appearance (D) are organizational preferences, not educational requirements. Definition length (C) does not affect concept sequencing.
**Concept Tested:** Learning Graph Structure
**See:** [Learning Graph](../concepts/learning-graph.md#prerequisites)Formatting Checklist
- [ ] Level-4 header with question number
- [ ] Complete sentence ending with ?
- [ ]
<div class="upper-alpha" markdown>wrapper - [ ] Numbered list (1, 2, 3, 4) for options
- [ ] Closing
</div>tag - [ ]
??? question "Show Answer"admonition - [ ] 4-space indentation in answer block
- [ ] "The correct answer is [LETTER]." statement
- [ ] Explanation (50-100 words)
- [ ] Concept Tested: label
- [ ] See: link with proper path
- [ ] Blank lines before and after div
Common Pitfalls to Avoid
Format Errors:
- ❌ Forgetting
<div class="upper-alpha" markdown>wrapper - ❌ Using letters (A, B, C, D) instead of numbers in list
- ❌ Incorrect indentation in answer block
- ❌ Missing closing
</div>tag
Question Quality:
- ❌ Ambiguous questions with multiple correct answers
- ❌ "All of the above" or "None of the above" options
- ❌ Trick questions or word games
- ❌ Questions testing trivial facts
Distractor Quality:
- ❌ Obviously wrong answers
- ❌ Joke options or nonsense
- ❌ Distractors much longer/shorter than correct answer
- ❌ Options that overlap or contradict
Explanation Quality:
- ❌ Just restating the question
- ❌ No teaching value
- ❌ Missing or broken links
- ❌ Too brief (< 30 words) or too long (> 150 words)
Output Files Summary
Required (Per Chapter): 1. Quiz markdown file (separate or embedded) 2. Quiz metadata JSON
Recommended (Aggregate): 3. docs/learning-graph/quiz-bank.json - All questions database 4. docs/learning-graph/quiz-generation-report.md - Quality metrics
Optional: 5. docs/learning-graph/quizzes/alternative-questions.json - Alternative questions 6. docs/[section]/[chapter-name]-study-guide.md - Study guide 7. Navigation updates to link quizzes
Example Session
User: "Generate a quiz for Chapter 3"
Claude (using this skill):
1. Assesses Chapter 3 content readiness (score: 82/100) 2. Determines chapter type: intermediate 3. Sets target distribution: 25% Remember, 30% Understand, 30% Apply, 15% Analyze 4. Identifies 12 concepts to test (10 priority 1, 2 priority 2) 5. Generates 10 questions using question admonition format 6. Creates quality distractors 7. Ensures answer balance (A: 2, B: 3, C: 3, D: 2) 8. Writes explanations with links 9. Creates metadata JSON 10. Updates quiz bank 11. Reports: "Created 10-question quiz for Chapter 3. Quality score: 78/100. Bloom's distribution: 2 Remember, 3 Understand, 3 Apply, 2 Analyze. Concept coverage: 83%."
Step 14: Update Site Navigation to Include Quizzes and Reports
Now update the mkdocs.yml file to include the quizzes in each chapter directory.
Use a format similar to this: where the chapter content in the index.md and the quiz file each have a different line under the chapter.
nav:
...
- Chapters:
- Overview: chapters/index.md
- Chapter 1 - Introduction to AI and Intelligent Textbooks:
- Content: chapters/01-intro-ai-intelligent-textbooks/index.md
- Quiz: chapters/01-intro-ai-intelligent-textbooks/quiz.md
- Chapter 2 - Getting Started with Claude and Skills:
- Content: chapters/02-getting-started-claude-skills/index.md
- Quiz: chapters/02-getting-started-claude-skills/quiz.md
- Chapter 3 - Course Design and Educational Theory:
- Content: chapters/03-course-design-educational-theory/index.md
- Quiz: chapters/03-course-design-educational-theory/quiz.mdNext, update the mkdocs.yml to include the quiz quality reports that have been placed in the learning-graph directory.
nav:
...
Learning Graph:
...
Quiz Generation Report: learning-graph/quiz-generation-report.mdStep 15: Write Session Log File
Export the session information to logs/quiz-generator-YYYY-MM-DD.md where YYYY-MM-DD is the current date.
Step 15: Write Session Log File
Notify the user that the site navigation section of the mkdocs.yml file has been updated to include both the links to the new quizzes as well as the quiz reports in the learning-graph. Tell them that the session has been logged to logs/quiz-generator-YYYY-MM-DD.md
Quiz Generator Skill
Automatically generate interactive multiple-choice quizzes for textbook chapters with Bloom's Taxonomy alignment and mkdocs-material question admonition formatting.
Overview
This skill converts chapter content into high-quality multiple-choice quiz questions. Questions are aligned to learning graph concepts, distributed across Bloom's Taxonomy cognitive levels, and formatted using mkdocs-material question admonitions with upper-alpha (A, B, C, D) answer choices.
Installation
To use this skill with Claude Code or Claude.ai:
1. Install the skill by providing the path to this directory 2. The skill will be available for Claude to use when generating quizzes
Usage
Trigger Phrases:
- "Generate a quiz for Chapter 3"
- "Create quiz questions for my chapter"
- "Build a quiz from this content"
- "Generate quizzes for all chapters"
Prerequisites:
- Chapter content exists (1000+ words per chapter recommended)
- Learning graph created (
docs/learning-graph/03-concept-dependencies.csv) - Glossary available (
docs/glossary.md) - recommended - Course description with learning outcomes - optional
Typical Workflow:
1. User asks Claude to generate quiz for specific chapter 2. Skill assesses content readiness (score 1-100) 3. Skill determines chapter type and Bloom's distribution 4. Skill generates 8-12 questions using question admonition format 5. Skill creates quiz markdown and metadata files 6. Skill updates quiz bank and generates quality report
Question Format
All questions use the mkdocs-material question admonition format:
#### 1. What is the primary purpose of a learning graph?
<div class="upper-alpha" markdown>
1. To create visual decorations for textbooks
2. To map prerequisite relationships between concepts
3. To generate random quiz questions
4. To organize files in a directory structure
</div>
??? question "Show Answer"
The correct answer is **B**. A learning graph is a directed graph that maps prerequisite relationships between concepts, showing which concepts must be learned before others.
**Concept Tested:** Learning Graph
**See:** [Learning Graph Concept](../concepts/learning-graph.md)Key Formatting Elements:
- Level-4 header (####) with question number
<div class="upper-alpha" markdown>wrapper for upper-alpha styling- Numbered list (1, 2, 3, 4) that renders as A, B, C, D
??? question "Show Answer"admonition- Indented answer block (4 spaces)
- "The correct answer is [LETTER]." statement
- Concept tested and source link
Output Files
Required (Per Chapter)
1. Quiz Markdown File
Location options:
- Separate:
docs/[section]/[chapter-name]-quiz.md - Embedded: Appended to chapter file
Content:
- 8-12 multiple choice questions
- Question admonition format
- Complete explanations
- Links to chapter sections
2. Quiz Metadata JSON
Location: docs/learning-graph/quizzes/[chapter-name]-quiz-metadata.json
Contains:
- Question metadata (Bloom's level, difficulty, concept)
- Answer distribution statistics
- Bloom's distribution
- Concept coverage
- Quality scores
Recommended (Aggregate)
3. Quiz Bank JSON
Location: docs/learning-graph/quiz-bank.json
Contains:
- All questions from all chapters
- Searchable by concept, Bloom's level, difficulty
- Ready for LMS export or chatbot integration
4. Quality Report
Location: docs/learning-graph/quiz-generation-report.md
Contains:
- Overall statistics
- Per-chapter quality scores
- Bloom's Taxonomy distribution
- Answer balance analysis
- Concept coverage
- Recommendations
Optional
5. Alternative Question Bank
Location: docs/learning-graph/quizzes/alternative-questions.json
Contains:
- 2-3 alternative questions per concept
- For quiz randomization or variations
6. Study Guide
Location: docs/[section]/[chapter-name]-study-guide.md
Contains:
- Key concepts to review
- Practice questions
- Links to chapter sections
Quality Standards
Content Readiness Score (1-100)
Assesses whether chapter content is sufficient for quality quiz:
- 90-100: Rich content (2000+ words, examples, clear concepts)
- 70-89: Good content (1000-2000 words, some examples)
- 50-69: Basic content (500-1000 words, limited examples)
- Below 50: Insufficient content
Quiz Quality Score (1-100)
Five components:
1. Question Quality (30 pts): Clear, unambiguous, well-formed 2. Bloom's Distribution (25 pts): Matches target for chapter type 3. Concept Coverage (20 pts): Tests 75%+ of major concepts 4. Answer Balance (15 pts): Correct answers evenly distributed 5. Pedagogical Value (10 pts): Explanations teach, links provided
Bloom's Taxonomy Targets
Introductory Chapters:
- 40% Remember, 40% Understand, 15% Apply, 5% Analyze
Intermediate Chapters:
- 25% Remember, 30% Understand, 30% Apply, 15% Analyze
Advanced Chapters:
- 15% Remember, 20% Understand, 25% Apply, 25% Analyze, 10% Evaluate, 5% Create
Success Criteria
- Overall quality score > 70/100
- 8-12 questions generated
- Bloom's distribution within ±15% of target
- 75%+ concept coverage
- Answer balance within 20-30% per option (A, B, C, D)
- 100% questions have explanations
- No duplicate questions
- All links valid
Skill Contents
quiz-generator/
├── SKILL.md # Main skill instructions
├── README.md # This file
└── references/
└── distractor-writing-guide.md # Detailed distractor guidanceExample Output
Quiz File (docs/concepts/learning-graph-quiz.md):
# Quiz: Learning Graphs
Test your understanding of learning graphs with these questions.
---
#### 1. What is the primary purpose of a learning graph?
<div class="upper-alpha" markdown>
1. To create visual decorations for textbooks
2. To map prerequisite relationships between concepts
3. To generate random quiz questions
4. To organize files in a directory structure
</div>
??? question "Show Answer"
The correct answer is **B**. A learning graph is a directed graph that maps prerequisite relationships between concepts, ensuring students learn foundational concepts before advanced ones.
**Concept Tested:** Learning Graph
**See:** [Learning Graph Concept](../concepts/learning-graph.md)
---
#### 2. Which data structure prevents cycles in a learning graph?
<div class="upper-alpha" markdown>
1. Linked list
2. Directed acyclic graph
3. Directed cyclic graph
4. Undirected graph
</div>
??? question "Show Answer"
The correct answer is **B**. A directed acyclic graph (DAG) is specifically designed to prevent cycles, which is essential for learning graphs because circular dependencies would create impossible prerequisite chains.
**Concept Tested:** Directed Acyclic Graph
**See:** [Learning Graph Structure](../concepts/learning-graph.md#structure)
---
[Continue with remaining questions...]Quality Report (excerpt):
# Quiz Generation Quality Report
## Chapter: Learning Graphs
- **Total Questions:** 10
- **Overall Quality Score:** 82/100
- **Content Readiness:** 88/100
## Bloom's Taxonomy Distribution
| Level | Actual | Target | Deviation |
|-------|--------|--------|-----------|
| Remember | 20% | 25% | -5% ✓ |
| Understand | 30% | 30% | 0% ✓ |
| Apply | 30% | 25% | +5% ✓ |
| Analyze | 20% | 15% | +5% ✓ |
**Bloom's Score:** 24/25 (excellent)
## Answer Balance
- A: 20% (2/10)
- B: 30% (3/10)
- C: 30% (3/10)
- D: 20% (2/10)
**Balance Score:** 14/15 (good)
## Concept Coverage
- **Total Concepts:** 12
- **Tested Concepts:** 10
- **Coverage:** 83%
**Coverage Score:** 17/20 (good)References
Distractor Writing Guide
The skill includes comprehensive guidance on writing quality distractors in references/distractor-writing-guide.md. This reference covers:
- The four qualities of effective distractors (plausibility, educational value, discrimination, fairness)
- Distractor construction patterns
- Common mistakes to avoid
- Quality checklist
- Examples by Bloom's level
- Revision strategies
Claude will reference this document when creating answer options.
Best Practices
For Users
1. Ensure sufficient content - 1000+ words per chapter for quality quizzes 2. Review generated quizzes - Check for accuracy and appropriate difficulty 3. Validate links - Ensure all references point to correct sections 4. Test rendering - Preview questions in mkdocs to verify formatting 5. Iterate as needed - Refine based on quality report recommendations
For Quiz Generation
1. Balance Bloom's levels - Don't over-focus on Remember/Understand 2. Create quality distractors - All wrong answers should be plausible 3. Write teaching explanations - Don't just confirm, explain why 4. Vary correct answer position - Avoid patterns (all C's, alternating, etc.) 5. Link to sources - Reference chapter sections for deeper learning 6. Test major concepts - Focus on important concepts, not trivial details
Troubleshooting
"Content readiness score is low (<60)"
Cause: Chapter has insufficient content for quality quiz
Solution:
- Write more chapter content (target: 1000+ words)
- Add examples for key concepts
- Ensure concepts are clearly explained
- Verify glossary coverage
"Bloom's distribution is imbalanced"
Cause: Too many questions at one cognitive level
Solution:
- Review chapter type (introductory, intermediate, advanced)
- Check target distribution for that chapter type
- Add more higher-level questions (Apply, Analyze, Evaluate)
- Reduce excessive Remember/Understand questions
"Answer balance is poor"
Cause: Correct answers clustered on one option (e.g., all B's)
Solution:
- Randomize correct answer placement
- Target: 25% each for A, B, C, D (±5% acceptable)
- Avoid patterns (A-B-A-B, all C's, etc.)
- Check after each question added
"Question admonition not rendering"
Cause: Formatting error in markdown
Solution:
- Verify
<div class="upper-alpha" markdown>wrapper present - Check numbered list uses 1, 2, 3, 4 (not A, B, C, D)
- Ensure closing
</div>tag exists - Verify 4-space indentation in answer block
- Check blank lines before and after div
"Distractors are too obvious"
Cause: Wrong answers not plausible
Solution:
- Review distractor writing guide
- Use related terminology
- Base on common misconceptions
- Ensure similar length to correct answer
- Avoid nonsense or joke options
Version History
- v1.0 (2025-01-31) - Initial release
- Question admonition format with upper-alpha styling
- Bloom's Taxonomy distribution
- Quality distractor analysis
- LMS-ready JSON export
- Comprehensive quality scoring
License
MIT License - See LICENSE file for details
Support
For issues, questions, or improvements:
1. Review detailed specification in /docs/skills/quiz-generator.md 2. Check distractor writing guide for answer option help 3. Examine quality reports for specific guidance 4. Test question rendering in mkdocs preview
Related Skills
- Learning Graph - Generates concept dependencies used for question selection
- Glossary Generator - Creates glossary referenced for terminology questions
- Chapter Content Generator - Produces content analyzed for quiz questions
- FAQ Generator - Creates FAQ questions (complementary to quiz questions)
- Concept Validator - Validates quiz coverage of all concepts
Distractor Writing Guide
This reference provides detailed guidance on creating high-quality distractors (wrong answer options) for multiple-choice quiz questions.
What Makes a Good Distractor?
Good distractors serve an educational purpose: they test understanding and reveal common misconceptions rather than just providing filler options.
The Four Qualities of Effective Distractors
1. Plausibility - Seems reasonable to someone who hasn't mastered the content 2. Educational Value - Tests understanding or reveals misconceptions 3. Discrimination - Helps distinguish between different levels of knowledge 4. Fairness - Not trick questions or unfair traps
Plausibility
Definition
A plausible distractor is one that appears correct to someone who has not fully learned the material, but is clearly wrong to someone who has mastered it.
Techniques for Creating Plausible Distractors
1. Use Related Terminology
❌ Implausible: Question: "What is a learning graph?"
- A) A graph made of learned behavior
- B) A directed graph showing concept dependencies ✓
- C) A banana
- D) The alphabet
✓ Plausible:
- A) A graph showing student learning over time
- B) A directed graph showing concept dependencies ✓
- C) A taxonomy of educational objectives
- D) A visual representation of course grades
2. Similar Length and Structure
All options should be roughly the same length to avoid the "longest answer is correct" tell.
❌ Implausible (length gives it away):
- A) Yes ✓
- B) No
- C) Sometimes, depending on specific contextual factors and prerequisites
- D) Maybe
✓ Plausible (balanced lengths):
- A) When all prerequisites are met ✓
- B) When the instructor approves
- C) When the student requests it
- D) When the semester begins
3. Grammatically Consistent
All options should fit grammatically with the question stem.
❌ Implausible (grammar mismatch): Question: "A learning graph is best described as..."
- A) map prerequisite relationships ✓
- B) showing relationships
- C) to organize
- D) visual
✓ Plausible (grammatically parallel): Question: "A learning graph is best described as..."
- A) a structure that maps prerequisites ✓
- B) a tool that visualizes progress
- C) a system that organizes content
- D) a framework that sequences topics
Educational Value
Definition
An educationally valuable distractor addresses common misconceptions, tests related concepts, or helps differentiate between levels of understanding.
Common Misconception Patterns
1. Partial Truth (Correct in Different Context)
This distractor is true but doesn't answer the specific question being asked.
Example: Question: "What is the PRIMARY purpose of a learning graph?"
- A) To create visual aids for presentations
- B) To map prerequisite relationships ✓
- C) To assess student performance
- D) To organize course materials
Analysis: A, C, and D might be benefits or uses of learning-related tools, but B is the primary purpose.
2. Reversal (Opposite or Inverse)
This distractor reverses the correct relationship or concept.
Example: Question: "In a learning graph, an arrow from Concept A to Concept B indicates..."
- A) Concept A must be learned before Concept B ✓
- B) Concept B must be learned before Concept A
- C) Concepts A and B are unrelated
- D) Concepts A and B are equivalent
Analysis: B is the opposite of the correct answer, testing whether students understand the direction of dependencies.
3. Similar Terminology (Related but Distinct)
Use terms from related concepts that students might confuse.
Example: Question: "What structure prevents cycles in a learning graph?"
- A) Linked list
- B) Directed acyclic graph ✓
- C) Directed cyclic graph
- D) Undirected graph
Analysis: C is very similar to B but critically different (cyclic vs. acyclic).
4. Common Student Error
Based on typical misunderstandings or mistakes students make.
Example: Question: "When should scaffolding be removed?"
- A) At the beginning of instruction
- B) Gradually as competence increases ✓
- C) Never, it should remain permanent
- D) Immediately after introduction
Analysis: A and D reflect a common misunderstanding that scaffolding should be removed too quickly. C reflects the opposite error.
---
Discrimination
Definition
Discriminating distractors help identify different levels of student understanding, from no knowledge to partial understanding to mastery.
Levels of Distractor Discrimination
No Knowledge → Partial Understanding → Mastery
Create distractors that appeal to different knowledge levels:
Example:
Question: "What does ISO 11179 compliance require for glossary definitions?"
- A) Definitions must be in alphabetical order (No knowledge - confuses organization with quality)
- B) Definitions must be long and detailed (Partial understanding - knows definitions need detail but not the specific requirements)
- C) Definitions must be precise, concise, distinct, and non-circular ✓ (Mastery - knows the four criteria)
- D) Definitions must include examples (Partial understanding - knows examples are helpful but confuses with requirements)
Knowledge Levels Tested:
- A appeals to someone with no knowledge of ISO 11179
- B and D appeal to someone with partial understanding
- C requires mastery of the specific criteria
---
Fairness
Definition
Fair distractors test knowledge of the subject matter, not test-taking skills, reading comprehension, or trivial details.
Unfair Distractor Patterns to Avoid
1. Trick Questions
❌ Unfair: Question: "What is the BEST data structure for a learning graph?"
- A) Directed acyclic graph ✓
- B) Directed acyclic graph
Analysis: Having two identical options is a trick, not a test of knowledge.
2. Trick Wording
❌ Unfair: Question: "Which of the following is NOT not important?"
- A) Prerequisites
- B) Dependencies ✓
- C) Scaffolding
- D) Examples
Analysis: Double negatives make this confusing and test reading comprehension rather than knowledge.
3. "All of the Above" / "None of the Above"
❌ Avoid:
- A) Learning graphs
- B) Concept dependencies
- C) Scaffolding
- D) All of the above
Why avoid: Reduces the question to binary (all vs. not all) rather than testing specific knowledge.
Exception: Can be used if it has educational value, but generally avoid.
4. Overly Specific or Trivial Details
❌ Unfair: Question: "On what page of the textbook is the learning graph definition?"
- A) Page 42
- B) Page 45 ✓
- C) Page 48
- D) Page 51
Analysis: Tests memorization of trivial details, not understanding.
5. Absolute Words
❌ Too obvious:
- A) Learning graphs ALWAYS solve every educational problem
- B) Learning graphs NEVER have any issues
- C) Learning graphs can help organize concept dependencies ✓
- D) Learning graphs are COMPLETELY unnecessary
Analysis: "Always," "never," "completely" signal obviously wrong answers.
---
Distractor Construction Patterns
Pattern 1: Related Concepts
Use concepts from the same domain that students might confuse.
Example (Educational Technology): Question: "What is a MicroSim?"
- A) A small-scale embedded simulation ✓
- B) A microscopic organism studied in biology
- C) A simulation of microprocessor operations
- D) A miniature physical model
All options contain "micro" and "sim" but only A is correct in context.
Pattern 2: Partial Definitions
Take parts of the correct definition and combine with incorrect elements.
Example: Correct definition: "A directed graph that maps prerequisite relationships between concepts"
Distractor options:
- "A directed graph that visualizes student progress" (right structure, wrong purpose)
- "An undirected graph that maps prerequisite relationships" (right purpose, wrong structure)
- "A directed list that shows learning order" (wrong structure, related purpose)
Pattern 3: Degree or Extent
Vary the strength or extent of a statement.
Example: Question: "How much of a chapter's concepts should be covered in a quiz?"
- A) 25-50%
- B) 50-75%
- C) 75-85% ✓
- D) 100%
All plausible, but C represents the recommended target.
Pattern 4: Timing or Sequence
Vary when or in what order something occurs.
Example: Question: "When should scaffolding begin to be removed?"
- A) Before instruction starts
- B) During initial instruction
- C) As competence develops ✓
- D) Long after mastery is achieved
---
Quality Checklist
For each distractor, verify:
- [ ] Plausible: Would seem correct to someone who hasn't learned the material?
- [ ] Educational: Tests understanding or reveals misconception?
- [ ] Grammatical: Fits with question stem grammatically?
- [ ] Appropriate Length: Similar length to correct answer?
- [ ] Fair: Not a trick or trivial detail?
- [ ] Distinct: Doesn't overlap with other options?
- [ ] Consistent Style: Uses same terminology/voice as other options?
- [ ] No Absolutes: Avoids "always," "never," "all," "none" (unless correct)?
---
Common Mistakes
Mistake 1: Nonsensical Options
❌ "What is a learning graph?"
- A) Purple elephants dancing
- B) The number 42
- C) A directed graph showing concept dependencies ✓
- D) My grandmother's recipe
Why wrong: Not plausible, has no educational value, insults students.
Mistake 2: One Distractor Much Longer
❌ "What is ISO 11179?"
- A) A car model
- B) A metadata registry standard that provides guidance for creating precise, concise, distinct, and non-circular definitions for use in glossaries and data dictionaries across organizations ✓
- C) A number
- D) A graph
Why wrong: Length signals the correct answer.
Mistake 3: Multiple Correct Answers
❌ "Which is important for learning?"
- A) Prerequisites ✓
- B) Practice ✓
- C) Examples ✓
- D) Sleep ✓
Why wrong: All could be defended as correct, making question ambiguous.
Mistake 4: Overlapping Options
❌ "What percentage is good concept coverage?"
- A) 50-70%
- B) 60-80% ✓
- C) 70-90%
- D) 80-100%
Why wrong: Options overlap; 70% could be B or C.
---
Distractor Quality Score
Rate each distractor on a 0-1 scale:
1.0 (Excellent):
- Highly plausible
- Tests understanding
- Discriminates knowledge levels
- Fair and educational
0.8 (Good):
- Plausible
- Has educational value
- Fair
- Minor issues
0.6 (Adequate):
- Somewhat plausible
- Some educational value
- Fair but could be better
0.4 (Poor):
- Not very plausible
- Limited educational value
- May be slightly unfair
0.2 (Very Poor):
- Implausible
- No educational value
- Potentially unfair
0.0 (Unacceptable):
- Nonsensical
- Trick question
- Clearly unfair
Overall Question Distractor Quality: Average the three distractor scores.
Target: 0.80+ average distractor quality
---
Examples by Bloom's Level
Remember Level
Good distractors use related terms or similar concepts.
Question: "What does DAG stand for?"
- A) Data Analysis Graph
- B) Directed Acyclic Graph ✓
- C) Digital Academic Guide
- D) Dynamic Assessment Grid
All distractors use the same initials with plausible terms.
Understand Level
Good distractors test depth of understanding.
Question: "Why is a learning graph directed?"
- A) To make it look more professional
- B) To show which concepts depend on others ✓
- C) To save storage space
- D) To make it easier to draw
B requires understanding the purpose; others are plausible to non-learners.
Apply Level
Good distractors present plausible but incorrect applications.
Question: "When creating a learning graph for a new course, what should you do first?"
- A) Draw the visual layout
- B) Choose graph visualization software
- C) Identify core concepts ✓
- D) Determine the color scheme
All sound like reasonable steps, but C must come first.
Analyze Level
Good distractors require distinguishing between related elements.
Question: "What indicates a poorly structured learning graph?"
- A) More than 100 concepts
- B) Cycles in the dependency structure ✓
- C) Use of technical terminology
- D) Complex visual layout
Requires analyzing what makes a learning graph valid vs. invalid.
---
Revision Strategies
If a distractor is too obvious or not plausible:
1. Add specificity: Make it more detailed and realistic 2. Use domain terminology: Incorporate correct vocabulary 3. Base on misconceptions: Research common student errors 4. Check parallel structure: Ensure grammatical consistency 5. Adjust length: Match other options 6. Test plausibility: Would a non-learner choose this?
---
Final Advice
The Golden Rule:
Every distractor should be something a reasonable student who hasn't learned the material might genuinely believe to be correct.
The Educational Rule:
Every distractor should help you understand what the student does or doesn't know.
The Fairness Rule:
Every distractor should test subject knowledge, not test-taking skills.