Thematic Technical Documentation Generator

Generate publication-quality technical manuals with thematic storytelling through multi-agent orchestration.

What This Does

Transform dry technical topics into engaging, memorable documentation using:

• Multi-agent parallel workflow - 2 research + N chapter + 3 assembly agents
• Thematic metaphor system - Complex concepts through memorable metaphors
• AI-generated illustrations - Custom artwork matching theme (optional)
• Professional structure - Front matter, back matter, index, glossary
• Publication pipeline - Pandoc conversion to PDF/HTML/EPUB (optional)
• Quality enforcement - 95%+ QA score requirement

When to Use

Invoke this skill when creating:

• Technical documentation with personality and narrative
• Training materials that need to be memorable
• Onboarding guides that people actually want to read
• Comprehensive technical manuals (20K+ words)
• Documentation that stands out from typical reference material

How It Works

6-Phase Workflow

Phase 1: Adversarial Research (15-30 min)

• Theme Designer proposes visual identity and metaphor system
• Structure Architect critiques and designs chapter structure
• Output: THEME_PROPOSAL.md (synthesized specification)

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

• N chapter agents write simultaneously (self-contained chapters)
• Each follows theme proposal for consistency
• Output: CHAPTER_01_*.md through CHAPTER_N_*.md

Phase 3: Publisher Assembly (15-30 min)

• Synthesizes chapters into complete manual
• Adds front matter (foreword, TOC, usage guide)
• Adds back matter (appendices, index, glossary, statistics)
• Output: THE_COMPLETE_MANUAL.md

Phase 4: Illustration Generation (15-30 min, optional)

• Generates 6-8 AI images via fal-text-to-image
• Maintains theme consistency
• Gracefully skips if fal unavailable
• Output: images/*.png + integration guides

Phase 5: Builder Pipeline (5-10 min, optional)

• Generates theme-specific CSS from THEME_PROPOSAL.md
• Converts MD → PDF/HTML/EPUB using pandoc
• Optional: GitHub Pages deployment, Algolia search
• Output: build/ directory with all formats

Phase 6: QA Validation (15-30 min)

• Validates structural integrity, theme consistency, technical accuracy
• Scores deliverables (minimum 95% required)
• Output: QA_FINAL_REPORT.md with APPROVED/REJECTED

Parameters

Configure the manual generation:

topic: "Technical subject to document"
theme: "Thematic metaphor/aesthetic (Victorian, pharmaceutical, etc.)"
audience: "beginner|intermediate|expert practitioners"
chapters: 8  # 5-12 range
word_count: {min: 2500, max: 3500}  # per chapter
include_illustrations: true  # requires fal-text-to-image
illustration_count: 6  # 3-10 range
character_guide: true  # mascot narrator
output_dir: "./docs/manual"
output_format: ["markdown", "pdf", "html", "epub"]

Examples

Example 1: Nyquil Cat ComfyUI Manual

topic: "ComfyUI for absolute beginners"
theme: "Nyquil Cat - drowsy pharmaceutical guide"
chapters: 8
include_illustrations: true

Output: 47,633 words, 8 chapters, 8 AI illustrations, 97.8% QA score

Example 2: Victorian Railway Git Manual

topic: "git worktree safety and best practices"
theme: "Victorian railway operations (1880s-1920s)"
chapters: 6
character: "Cornelius Worktree, Chief Railway Dispatcher"

Output: 30,606 words, 6 chapters, 6 illustrations, 98.4% QA score

Execution

When user requests themed manual:

1. Validate fal availability (if illustrations requested)
2. Create output directory
3. Launch Phase 1 - Theme Designer + Structure Architect agents in parallel
4. Launch Phase 2 - N chapter agents in parallel
5. Launch Phase 3 - Publisher agent (sequential)
6. Launch Phase 4 - Illustrator agent (optional, sequential)
7. Launch Phase 5 - Builder agent (optional, sequential)
8. Launch Phase 6 - QA agent (sequential, final gate)

Do NOT skip illustrator phase - validate fal availability, prompt user if missing.

Total execution: ~90-180 minutes for 8-chapter manual with illustrations.

Quality Standards

Enforce these minimums:

• Overall QA score ≥ 95%
• Zero critical issues
• Zero major issues
• Theme consistency: 100%
• Technical accuracy: 100%
• Chapter delivery: ≥75%

Output Structure

output_dir/
├── THEME_PROPOSAL.md
├── THE_COMPLETE_MANUAL.md (primary deliverable)
├── CHAPTER_01_*.md through CHAPTER_N_*.md
├── images/
│   ├── 01_cover_hero.png
│   ├── 02_character_portrait.png
│   └── ...
├── build/ (if builder enabled)
│   ├── THE_COMPLETE_MANUAL.pdf
│   ├── THE_COMPLETE_MANUAL.html
│   ├── THE_COMPLETE_MANUAL.epub
│   └── manual.css
├── IMAGE_INTEGRATION_GUIDE.md
├── ILLUSTRATION_SUMMARY.md
├── QA_FINAL_REPORT.md
└── MANUAL_README.md

Dependencies

Required:

• Task tool (for agent orchestration)
• Read, Write, Edit tools
• Glob, Grep tools

Optional:

• fal-text-to-image skill (for illustrations)
• pandoc (for PDF/HTML/EPUB)
• xelatex or pdflatex (for PDF generation)

Agent References

All agent prompts in prompts/ directory:

• research-theme.md - Theme Designer
• research-structure.md - Structure Architect
• chapter-orchestrator.md - Chapter Writer (generic)
• publisher.md - Publisher
• illustrator.md - Illustrator
• builder.md - Builder (pandoc pipeline)
• qa-orchestrator.md - QA Validator

Templates

Pandoc templates in templates/ directory:

• dummies-book.css - Theme-specific CSS generation template
• pandoc-template.tex - LaTeX template for PDF
• metadata-template.yaml - Pandoc metadata
• cover-template.svg - Editable cover design

Success Criteria

Manual is complete when:

• QA score ≥ 95%
• All planned chapters delivered (or gracefully noted as missing)
• Theme consistency validated
• Technical accuracy verified
• No placeholders or TODOs
• Ready for publication or distribution