thematic-doc-generator（专题文档生成器）

Thematic Technical Documentation Generator

Generate comprehensive, publication-quality technical manuals with thematic storytelling using multi-agent orchestration.

What This Skill Does

Transforms dry technical topics into engaging, memorable documentation through:

• Multi-agent parallel content generation - 8 chapters written simultaneously
• Thematic metaphor system - Make complex topics memorable (e.g., git → Victorian railways)
• AI-generated illustrations - Custom artwork matching your theme
• Publication-ready output - Professional structure with front/back matter
• Automated quality assurance - 98%+ quality scores with comprehensive validation

When to Use

• Creating internal technical documentation with personality
• Generating training materials that need to be memorable
• Building comprehensive guides that stand out from typical docs
• Transforming complex topics into accessible narratives
• Team onboarding materials that people actually want to read

Example Usage

Basic Usage

# Generate a Victorian railway-themed git worktree manual
Use this skill with:
  topic: "git worktree safety and best practices"
  theme: "Victorian railway operations (1880s-1920s)"
  chapters: 8
  include_illustrations: true

Advanced Usage

# Art Deco automation theme for API documentation
Use this skill with:
  topic: "microservices architecture patterns"
  theme: "Art Deco automation and streamlined design"
  audience: "intermediate DevOps engineers"
  chapters: 10
  word_count: {min: 3000, max: 4000}
  illustration_count: 8
  character_guide: true
  output_dir: "./docs/architecture-manual"

Quick Reference Guide

# Minimal setup for quick guide (no illustrations)
Use this skill with:
  topic: "Docker security best practices"
  theme: "Maritime navigation safety protocols"
  chapters: 5
  comprehensive_vs_quick: "quick-reference"
  include_illustrations: false

What You Get

Primary Deliverable:

• Complete manual (30,000+ words) in single markdown file
• Professional front matter (foreword, TOC, usage guide)
• Complete back matter (appendices, index, glossary, statistics)

Visual Assets (if illustrations enabled):

• 6-8 AI-generated illustrations matching theme
• High-resolution PNGs (1024px+ minimum dimension)
• Complete integration documentation
• Alt text for accessibility

Quality Documentation:

• Comprehensive QA report with metrics
• Theme consistency validation
• Technical accuracy verification
• Publication readiness assessment

Supporting Files:

• Individual chapter source files
• Theme proposal document
• Image integration guides
• Sample integration examples

Parameters

Required

Optional

How It Works

Phase 1: Adversarial Theme Research (15-30 min)

Two agents collaboratively design theme and structure, challenging each other's proposals.

Agents:

• Theme Designer: Proposes aesthetic, visual identity, tone, metaphor mappings
• Structure Architect: Challenges theme viability, proposes chapter outline

Output: THEME_PROPOSAL.md (synthesized vision both agents approve)

Phase 2: Parallel Content Generation (30-60 min)

Each chapter generated independently by specialized agent, all running concurrently.

Agents: N chapter agents (one per chapter, typically 8)

Outputs: CHAPTER_1_*.md through CHAPTER_N_*.md

Key Design: Chapters are self-contained with no cross-dependencies, enabling true parallelism.

Phase 3: Publisher Assembly (15-30 min)

Publisher agent synthesizes chapters into cohesive manual with transitions.

Tasks:

• Create front matter (title, copyright, foreword, TOC, usage guide)
• Integrate all chapters with smooth transitions
• Create back matter (appendices, index, glossary, statistics, colophon)
• Handle missing chapters gracefully

Output: THE_COMPLETE_MANUAL.md (unified publication)

Phase 4: Visual Enhancement (15-30 min, optional)

Illustrator generates thematic imagery using AI.

Tasks:

• Generate 6-8 illustrations matching theme
• Ensure visual consistency (color palette, era, style)
• Create comprehensive documentation
• Provide alt text for accessibility

Outputs: Images + integration guides

Phase 5: Quality Assurance (15-30 min)

QA agent validates all deliverables against quality standards.

Validates:

• Structural integrity (front/back matter complete)
• Theme consistency (no anachronisms, metaphor accuracy)
• Technical accuracy (code examples, commands)
• Documentation quality (completeness, accessibility)
• Publication readiness (no placeholders, proper licensing)

Output: QA_FINAL_REPORT.md with APPROVED/REJECTED recommendation

Success Stories

Victorian Railway Git Safety Manual

• Topic: Git worktree safety and best practices
• Theme: Victorian railway operations (1880s-1920s)
• Results:

- 30,606 words across 6 chapters - 6 Victorian illustrations (signal towers, brass instruments) - 98.4% quality score from QA - Publication-ready on first execution - Character: Cornelius Worktree (elderly railway dispatcher)

Excerpt:

"Dear Reader and Fellow Dispatcher, you hold in your hands a manual born of necessity. In the modern age of distributed version control, we find ourselves managing not merely a single line of development, but entire networks of parallel tracks..."

Tips for Best Results

Theme Selection

• Choose themes with rich visual vocabulary: Victorian, Art Deco, Space Age, Medieval
• Match theme to content domain when possible: Railways→branching, Architecture→structure
• Consider character potential: Who naturally exists in this world?
• Avoid overly abstract themes: Concrete metaphors work better

Scope Planning

• 8 chapters is optimal: Comprehensive coverage without overwhelming length
• Allow variance in chapter length: Quality > rigid word counts
• Plan for 75% completion: Missing 1-2 chapters is acceptable if acknowledged
• Front/back matter adds ~20%: Factor this into total length

Visual Enhancement

• Enable illustrations: Images significantly boost engagement
• 6 images is ideal: Cover, character, 4 concepts/diagrams
• Budget time for iteration: AI image generation may require refinement
• Document everything: Image prompts, models used, regeneration instructions

Quality Assurance

• Trust the QA gate: 95%+ scores indicate publication readiness
• Address critical issues only: Minor issues rarely block publication
• Expect some variance: Parallel agents produce slightly different styles
• Publisher smooths inconsistencies: Trust the synthesis process

Requirements

Essential

• Claude Code CLI with skill support
• Task orchestration capability
• File system write access
• Minimum context: ~100K tokens (for 8 chapters)

Optional

• fal-text-to-image skill (for illustrations)
• pandoc (for PDF export)
• Markdown linter (for validation)

Limitations

• Context window: Very large manuals (12+ chapters) may exceed limits
• AI image generation: Requires API access and credits (fal.ai)
• Execution time: 2-3 hours total (not instant)
• Theme quality: Success depends on metaphor strength
• Manual review: QA catches most issues but human review recommended

Troubleshooting

Problem: "Chapter agents incomplete"

• Solution: Retry failed chapters or accept partial completion with transitional notes

Problem: "Illustration generation fails"

• Solution: Check fal-text-to-image skill installation, API key, credits

Problem: "Context window exceeded"

• Solution: Reduce chapter count or word count targets

Problem: "Theme feels forced"

• Solution: Choose more natural metaphor, consult examples/

Problem: "QA rejects output"

• Solution: Review critical issues, re-run appropriate phase (usually chapter agents)

License

This skill is released under the Unlicense (public domain). Generated manuals inherit this license unless you specify otherwise.

Support

• Documentation: See docs/ directory in skill package
• Examples: See examples/ directory
• Issues: https://github.com/delorenj/thematic-doc-generator/issues

Generated manuals are publication-ready. No additional editing required (though always welcome).