dmccreary/claude-skills/dmccreary-claude-skills

FAQ Generator

Version: 1.0

Generate comprehensive, categorized FAQs from textbook content and chatbot-ready JSON exports. Place the FAQs into the file docs/faq.md. Log the results of the session to logs/faq.md.

Purpose

This skill automates FAQ creation for intelligent textbooks by analyzing course content, learning graphs, and glossary terms to generate relevant questions and answers. The skill organizes questions by category and difficulty, ensures Bloom's Taxonomy distribution across cognitive levels, provides answers with links to source content, and exports structured JSON data ready for RAG system integration.

When to Use This Skill

Use this skill after the following artifacts exist:

1. Course description has been finalized with a quality score above 70
2. Learning graph has been created
3. Glossary has been generated
4. At least 30% of chapter content has been written

Having these prerequisites ensures the FAQ generator has sufficient context to create meaningful, relevant questions. Trigger this skill when:

• Building initial FAQ for a new textbook
• Updating FAQ after significant content additions
• Preparing content for chatbot or AI assistant integration
• Identifying knowledge gaps in existing content

Markdown Formatting

1. Use markdown header level one (#) for the FAQ title
2. Use markdown header level two (##) for each category
3. Use markdown header level three (###) for each individual question
4. Place the answer in the body text

Use the faq-template.md in the skill references section as your template.

Critical Rule: No Anchor Links

!!! warning "NEVER Use Anchor Links" All links must point to files only, never with `#` anchor fragments.

Anchor links (file.md#section-name) break frequently because:

• Section headers change during content editing
• Anchors are case-sensitive and whitespace-sensitive
• MkDocs anchor auto-generation is unpredictable
• Broken anchors cause build warnings and confuse users

✅ Correct: [See Ohm's Law](chapters/02-ohms-law/index.md)

❌ Wrong: [See Ohm's Law](chapters/02-ohms-law/index.md#series-circuits)

Workflow

Step 1: Assess Content Completeness

Calculate a content completeness score (1-100 scale) to determine FAQ generation feasibility:

Required Inputs:

1. Read docs/course-description.md

• Check for: title, audience, prerequisites, learning outcomes
• Verify Bloom's Taxonomy outcomes present
• Score: 25 points if complete

1. Read docs/learning-graph/03-concept-dependencies.csv

• Validate DAG structure (no cycles)
• Count concepts and dependencies
• Score: 25 points if valid DAG with good connectivity

1. Read docs/glossary.md

• Count terms (50+ = good, 100+ = excellent)
• Score: 15 points for 100+, 10 for 50-99, 5 for <50

1. Scan all docs/**/*.md files

• Calculate total word count
• Target: 10,000+ words for comprehensive FAQ
• Score: 20 points for 10k+, 15 for 5k-10k, 10 for <5k

1. Calculate concept coverage

• What % of learning graph concepts have related chapter content?
• Score: 15 points for 80%+, 10 for 60-79%, 5 for <60%

Content Completeness Score Ranges:

• 90-100: All inputs present with high quality
• 70-89: Core inputs present, some content gaps
• 50-69: Missing optional inputs or low word count
• Below 50: Critical inputs missing

User Dialog Triggers:

• Score < 60: Ask "Limited content available for FAQ generation. Continue with basic FAQ or wait for more content?"
• No glossary: Ask "No glossary found. Generate FAQ anyway (limited technical questions) or create glossary first?"
• Low word count: Ask "Only [N] words of content found. FAQ quality may be limited. Proceed?"

If user agrees to proceed with score < 60, generate FAQ but include disclaimer in quality report about limited content.

Step 2: Analyze Content for Question Opportunities

Read and analyze all content sources to identify common question patterns:

From Course Description:

• "What is this course about?" (scope)
• "Who is this course for?" (audience)
• "What will I learn?" (outcomes)
• "What do I need to know first?" (prerequisites)

From Learning Graph:

• "What is [concept]?" (definition questions)
• "How does [concept A] relate to [concept B]?" (relationship questions)
• "What do I need to know before learning [concept]?" (prerequisite questions)
• "What comes after [concept]?" (progression questions)

From Glossary:

• "What does [term] mean?" (terminology questions)
• "What's the difference between [term A] and [term B]?" (comparison questions)
• "Can you give an example of [term]?" (application questions)

From Chapter Content:

• Identify recurring themes or topics
• Note areas where students might struggle (complex concepts)
• Extract common misconceptions if mentioned
• Find practical application examples

From Existing FAQ (if present):

• Read docs/faq.md if it exists
• Preserve manually curated questions
• Merge with new generated questions
• Remove duplicates, keeping manual version when conflict

Step 3: Generate Question Categories

Create 6 standard categories aligned with learning progression. For detailed guidance on writing questions at each Bloom's level (question starters, answer characteristics, common mistakes), read the canonical reference $BK_HOME/skills/chapter-content-generator/references/blooms-taxonomy.md.

1. Getting Started Questions (10-15 questions)

Target Bloom's levels: 60% Remember, 40% Understand

• Course overview and objectives
• Prerequisites and preparation
• How to use the textbook
• Navigation and structure
• Time commitment and difficulty

2. Core Concept Questions (20-30 questions)

Target Bloom's levels: 20% Remember, 40% Understand, 30% Apply, 10% Analyze

• Key concepts from learning graph (prioritize high-centrality nodes)
• Fundamental principles
• Concept relationships and dependencies
• How concepts build on each other

3. Technical Detail Questions (15-25 questions)

Target Bloom's levels: 30% Remember, 40% Understand, 20% Apply, 10% Analyze

• Terminology from glossary
• Definitions and explanations
• Technical comparisons
• Specification details

4. Common Challenges (10-15 questions)

Target Bloom's levels: 10% Remember, 30% Understand, 40% Apply, 20% Analyze

• Difficult concepts requiring extra explanation
• Common misconceptions
• Troubleshooting scenarios
• Error resolution

5. Best Practice Questions (10-15 questions)

Target Bloom's levels: 10% Understand, 40% Apply, 30% Analyze, 15% Evaluate, 5% Create

• How to apply concepts effectively
• Recommended approaches
• When to use specific techniques
• Real-world applications

6. Advanced Topics (5-10 questions)

Target Bloom's levels: 10% Apply, 30% Analyze, 30% Evaluate, 30% Create

• Complex integrations
• Edge cases
• Performance optimization
• Future directions

Step 4: Generate Questions and Answers

For each category, generate questions following these guidelines:

Question Format:

• Use level-2 headers (##)
• Write as actual questions (end with ?)
• Make questions specific and searchable
• Use terminology from glossary
• Keep questions concise (5-15 words)

Answer Format:

• Use a level 3 markdown header (###) for each question
• Write complete, standalone answers
• Include examples for 40% of answers
• Link to relevant sections (target: 60%+ linked)
• Target length: 100-300 words
• Use clear, direct language
• Address the question fully

Bloom's Taxonomy Guidelines:

Remember: Recall facts, terms, basic concepts

• "What is [concept]?"
• "What does [term] mean?"
• "What are the components of [system]?"

Understand: Explain ideas or concepts

• "How does [concept] work?"
• "Why is [concept] important?"
• "What is the difference between [A] and [B]?"

Apply: Use information in new situations

• "How do I [perform task]?"
• "When should I use [technique]?"
• "What's an example of [concept] in practice?"

Analyze: Draw connections among ideas

• "What is the relationship between [A] and [B]?"
• "How does [concept] relate to [other concept]?"
• "What are the underlying causes of [issue]?"

Evaluate: Justify a decision or stance

• "Which approach is best for [scenario]?"
• "What are the trade-offs of [technique]?"
• "How do I choose between [A] and [B]?"

Create: Produce new or original work

• "How would I design a [system] that [requirements]?"
• "What's the best way to combine [concepts]?"
• "How can I adapt [technique] for [new context]?"

Answer Quality Checklist:

• [ ] Use correct markdown headers for title, categories and questions
• [ ] Directly answers the question
• [ ] Uses terminology from glossary consistently
• [ ] Includes example if concept is abstract (40% target)
• [ ] Links to relevant chapter file (60% target) - NO anchor fragments
• [ ] Appropriate length (100-300 words)
• [ ] Clear and understandable for target audience
• [ ] Accurate based on textbook content
• [ ] No jargon unless defined in glossary
• [ ] Zero links with `#` anchors (hard requirement)

Step 5: Create FAQ File

Generate docs/faq.md with proper structure:

# [Course Name] FAQ
 
## Getting Started Questions
 
### What is this course about?
 
[Answer with overview, linking to course description]
 
### Who is this course for?
 
[Answer describing target audience]
 
[Continue with 10-15 Getting Started questions...]
 
## Core Concepts
 
### What is a [Key Concept]?
 
[Answer with definition and example, linking to chapter]
 
[Continue with 20-30 Core Concepts questions...]
 
## Technical Detail Questions
 
[Continue with terminology and technical questions...]
 
## Common Challenge Questions
 
[Continue with troubleshooting questions...]
 
## Best Practice Questions
 
[Continue with application questions...]
 
## Advanced Topic Questions
 
[Continue with advanced questions...]

Formatting Requirements:

• Use level-1 header for title
• Use level-2 headers for category names
• Use level-3 headers for questions
• Use body text for answers
• Use markdown links to chapter files: [text](path.md) - NEVER use anchor links
• Use bold for emphasis: **important term**
• Use code blocks for code: `language ``
• Maintain consistent spacing

CRITICAL: No Anchor Links

NEVER add anchor fragments (#section-name) to links. Anchors break frequently because:

• Section headers change during editing
• Anchors are case-sensitive and whitespace-sensitive
• MkDocs anchor generation is unpredictable
• Broken anchors cause build warnings and confuse users

✅ Correct: [Ohm's Law](chapters/02-ohms-law/index.md) ❌ Wrong: [Ohm's Law](chapters/02-ohms-law/index.md#series-circuits)

Link to the chapter file only. Users can navigate within the page themselves.

Step 6: Generate Chatbot Training JSON

Create docs/learning-graph/faq-chatbot-training.json for RAG integration: