name: tutorial-book-generator description: > Generate kid‑friendly, hands‑on tutorial books for any software project. Supports multiple subjects (backend, frontend, full‑stack, etc.) and three target lengths (50k, 100k, 200k words). Uses sequential sub‑agents with summary/last‑passage handoff for narrative coherence. Produces an assembled Markdown file, an EPUB with TOC, an OUTLINE.md, and a parts/ directory. triggers:

• “generate tutorial book”
• “write a book for”
• “create a step‑by‑step guide”
• “/tutorial-book” parameters:
• project_name: Name of the project (e.g., “FicHub”).
• project_path: Absolute path to the project source code.
• subjects: Comma‑separated list of subjects to cover (e.g., “backend,frontend,full‑stack”). Default: “full‑stack”.
• lengths: Comma‑separated list of target word counts (e.g., “50k,100k,200k”). Default: “100k”.
• output_root: Directory where books will be placed. Default: “{project_path}/books”.
• skip_existing: If true, skip lengths that already have a compiled Markdown file. Default: true.

Generic Tutorial Book Generator Skill

This skill defines a repeatable, project‑agnostic workflow for creating beginner‑friendly tutorial books that teach how to build a software project from scratch. It reads the actual source code, breaks the learning journey into parts and chapters, and produces polished Markdown and EPUB e‑books.

Output Structure

Books are organised under {output_root}/books/{subject}/{length}/:

{output_root}/
└── books/
    ├── {subject1}/
    │   ├── 50k/
    │   │   ├── {PROJECT_NAME}_{SUBJECT}_50K.md    # assembled markdown
    │   │   ├── {PROJECT_NAME}_{SUBJECT}_50K.epub   # ebook
    │   │   ├── OUTLINE.md
    │   │   └── parts/
    │   │       ├── 01-welcome/01-welcome.md
    │   │       ├── 02-core-setup/02-core-setup.md
    │   │       └── ...
    │   ├── 100k/ ...  (same layout)
    │   └── 200k/ ...
    ├── {subject2}/ ...
    └── ...

Filenames use the pattern: {PROJECT_NAME}_{SUBJECT}_{LENGTH}.md and .epub. For “full‑stack” subjects, the prefix BOOK_{PROJECT_NAME}_FULL_STACK_{LENGTH} can be used.

Workflow

1. Initialisation

• Verify that the project source exists at {project_path}.
• Ensure pandoc is installed (exit with a clear error if not).
• Create the base directory {output_root}/books (and sub‑directories) if needed.
• For each {subject} and {length} combination:
  • If {skip_existing} is true and the assembled .md file already exists, skip this combination.

2. Content Planning – Per Book

For each book to be generated:

1. Read the source code – crawl the project directory to understand the tech stack, architecture, key modules, and entry points. This grounds the book in reality.
2. Draft OUTLINE.md – define the book’s parts and chapters. The number of parts roughly follows:
   • 50k words → 7‑10 parts, ~30‑40 chapters
   • 100k words → 10‑13 parts, ~45‑55 chapters
   • 200k words → 14‑17 parts, ~70‑80 chapters Each part should cover a logical grouping of concepts (e.g., “Setting Up”, “Core Logic”, “Database”, “Deployment”).
3. Save the outline in the book’s folder (e.g., books/frontend/200k/OUTLINE.md).

3. Sequential Sub‑Agent Writing

Use one sub‑agent per part, running strictly sequentially.

• First sub‑agent input:
  • The OUTLINE.md content.
  • The project source path.
  • Instruction: “Write Part 1 ({title}) for the {subject} {length} book. Use a kid‑friendly Markdown style with real code examples from the project. Include 🧪 Try It Yourself, ⚠️ Watch Out, and 💡 Key Concept call‑out boxes. Return exactly the following at the end of your response: SUMMARY: … and LAST_PASSAGE: … so the next agent can continue seamlessly.”
• Subsequent sub‑agent input:
  • The OUTLINE.md content.
  • The summary and last passage from the previous sub‑agent.
  • Instruction: “Continue the book. Write Part N ({title}). The previous agent left off with: [LAST_PASSAGE]. Here is what they covered: [SUMMARY]. Maintain the same tone and style. Return SUMMARY and LAST_PASSAGE at the end.”
• Each sub‑agent writes its content to parts/{part-number}-{slug}/{part-number}-{slug}.md.
• If a sub‑agent hits a context limit, it saves partial work and passes enough handoff data to the next agent.

4. Assembly & Publishing

Once all parts are written:

1. Assemble Markdown – concatenate all part files in order, adding a YAML metadata block at the top:

   ---
   title: "Building {Project Name} – {Subject} {Length} Guide"
   author: "{Project Name} Contributors"
   date: "{today's date}"
   ---
   

   Save as {PROJECT_NAME}_{SUBJECT}_{LENGTH}.md.
2. Generate EPUB:

   pandoc "{assembled_md}" -o "{output_epub}" \
     --toc --toc-depth=2 \
     --metadata title="Building {Project Name} – {Subject} {Length} Guide" \
     --metadata author="{Project Name} Contributors"
   

3. Validate – ensure the word count is within ±10% of the target and that no Markdown errors exist.
4. Commit the result with a descriptive message (e.g., “feat: add {subject} {length}k tutorial book”).

Usage Examples

Generate all books for a project named “TaskLite”:

/tutorial-book project_name="TaskLite" project_path="~/code/tasklite" subjects="backend,frontend" lengths="50k,100k"

Generate only a 200k full‑stack guide for FicHub:

/tutorial-book project_name="FicHub" project_path="/home/user/code/rust/fichub" subjects="full-stack" lengths="200k"

Generate a single 50k backend book for any project in the current working directory:

Write a 50k backend tutorial book for this project.

(The agent should infer the project name and path from the workspace.)

Notes

• The skill uses sequential sub‑agents to maintain coherence; never run sub‑agents in parallel for the same book.
• The agent must read actual source files before writing any code examples or explanations.
• If a project does not have distinct “backend” / “frontend”, the subject list can be adapted to use module names (e.g., “scraper”, “cli”, “api”).