Make a Textbook — Skill Guide v1.2

Build a comprehensive graduate-level university textbook on any subject, complete with chapter outlines, worked examples, misconceptions, data tables, citations, glossary, and an index. Output: a professionally formatted PDF (~40-100 KB per book).

When to Use This Skill

Invoke when the user asks to "make a textbook," "write a textbook," "create a comprehensive learning resource" on any topic — from quantum mechanics to local AI agent infrastructure.

Workflow Overview

SUBJECT → OUTLINE → CHAPTER RESEARCH → CONTENT DRAFTING → QA → PDF GENERATION → DELIVER

Pass 1 — Outline Generation

1. Parse the topic into 6-12 chapters (~3-4 pages each)
2. Search the web for university syllabi, textbook tables of contents, and topic maps
3. Present a structured outline for user approval before proceeding

Part I / Section heading
  Chapter 1. [Title] — 1-2 sentence description
  Chapter 2. [Title] — ...

Pass 2 — Deep Research (Per Chapter)

• Search authoritative sources: lecture notes, open-access textbooks, peer-reviewed papers
• Collect facts, formulas, case studies, examples, statistics
• Verify facts across ≥2 independent sources
• Identify common misconceptions by searching "common misconceptions in [topic]"
• Collect worked examples with step-by-step solutions
• Log every source for IEEE citation format

Search strategy: Use batch_web_search for 8-10 concurrent searches per chapter. Combine broad searches with specific sub-topic queries.

Pass 3 — Content Drafting (Per Chapter)

Each chapter follows this structure:

CHAPTER N. [Title]
├─ N.0 Introduction (overview, prerequisites)
├─ N.1 [Core concept] — definitions, explanation, worked examples
├─ N.2 [Next concept] — ...
├─ ⚠ Common Misconceptions (callout box)
├─ N.3 Data Table (comparison or structured data)
└─ References (IEEE numbered)

Every chapter must include:

• ≥2 worked examples with full solution methodology
• ≥2 common misconceptions with corrections
• ≥1 data table
• IEEE citations embedded in-text
• Every technical term defined on first use

Pass 4 — Cross-Chapter QA

After drafting all chapters:

1. Check for contradictions between chapters
2. Check for missing definitions (terms used before being defined)
3. Verify citation integrity
4. Ensure notation is consistent across chapters

Pass 5 — PDF Generation

The PDF generator is at scripts/textbook_generator.py. It reads the JSON content file and produces a professional academic PDF with:

• Cover page: navy background, gold title text (multi-line wrapped), subtitle, date
• Table of contents: chapter list with sub-headings
• Chapter banners: navy with gold left border, chapter number, title
• Example boxes: blue accent bar, light-blue background
• Misconception boxes: orange accent bar, light-orange background
• Data tables: alternating row colours, navy headers
• Chapter summaries: bullet-point callout boxes
• Glossary: alphabetical by letter, bold term, indented definition
• References: hanging-indent IEEE format

Run it:

python3 scripts/textbook_generator.py textbook_content.json output/book.pdf

JSON Content Schema

The textbook_content.json file must conform to this schema:

{
  "title": "Topic Title",
  "subtitle": "Optional Subtitle",
  "date": "May 2026",
  "preface": "How to use this book...",
  "chapters": [
    {
      "number": 1,
      "title": "Chapter Title",
      "intro": "Chapter banner subtitle (optional)",
      "sections": [
        {"type": "heading",  "level": 1, "content": "Major Heading"},
        {"type": "heading",  "level": 2, "content": "Sub-heading"},
        {"type": "text",     "content": "Body text with **bold**, *italic*, `code` markup."},
        {"type": "example",   "title": "Example 1.1", "problem": "...", "solution": "..."},
        {"type": "misconception", "title": "Misconception: ...", "explanation": "..."},
        {"type": "table",    "header": true, "data": [["Col1","Col2"],["A","B"]]},
        {"type": "divider",  "content": ""}
      ],
      "summary": "- Key takeaway 1\
- Key takeaway 2"
    }
  ],
  "glossary": [
    {"term": "Term", "definition": "Definition sentence."}
  ],
  "full_references": [
    "[1] A. Author, Title, Source, Year."
  ]
}

Supported Section Types

Markup in text content

Error Handling & Fallbacks (v1.2 improvements)

The generator is resilient to malformed input:

• Missing data in a table section → table skipped silently, no crash
• Ragged table rows → padded to max column count automatically
• Non-string cell values → coerced to str
• Unknown section types → skipped silently (forward-compatible)
• Missing glossary / references → sections omitted, no crash
• Missing optional fields (subtitle, date, intro, preface) → replaced with ""
• Malformed JSON → clear error message printed to stderr, exit(1)
• PDF build failure → error message to stderr, exit(1)
• reportlab not installed → clear install instructions printed, exit(1)

Architecture Notes (for contributors)

• textbook_generator.py is pure Python 3, no external API calls
• ReportLab is the only hard dependency (pip install reportlab)
• Paths resolve relative to the skill root (parent of scripts/) — run from anywhere
• Page handler uses canvas.showPage() on page 1 to advance to page 2 for TOC
• All rendering functions (make_example, make_table, etc.) return a list of flowables; empty list means "skip gracefully" — never raise from a renderer
• See inline docstrings in textbook_generator.py for detailed per-function docs

Iteration Triggers

• Chapter too shallow: Expand with additional worked examples and data tables
• Missing sources: Return to Pass 2 for targeted sub-topic searches
• Outline rejected: Re-present with adjusted scope, chapter count, or emphasis
• Contradiction found in QA: Flag which chapter, return to that chapter's research