best-selling-book-writer

# Best-Selling Book Writer Complete AI-powered workflow: **topic selection → outline → chapters → cover design → KDP metadata → published book**. --- ## When to Use This Skill - User says: "写书 / write a book / start a new book project" - User says: "新建书籍项目 / create a book project" - User says: "设计封面 / design cover / 生成封面" - User says: "合并章节 / merge chapters / 生成电子书 / generate ebook" - User says: "导出 PDF 书 / export PDF book" - User says: "生成 KDP 元数据 / generate KDP metadata" - User needs to convert multiple Markdown chapters into a formatted book --- ## Core Principle **This skill is agent-agnostic.** It assumes only: - File system access (read/write files) - Ability to run Python scripts (`python3`) - Optional: `playwright` for PDF generation No references to any specific agent platform. Works identically in WorkBuddy, Claude Code, Codex, OpenClaw, Hermes, or any other AI coding agent. --- ## Project Directory Structure ``` {project_path}/ ├── book-config.json ← Book configuration (Phase 1) ├── outline.md ← Content outline (Phase 2) ├── kdp-metadata.json ← KDP publishing metadata (Phase 3, auto-generated) ├── chapters/ ← All chapter files (Phase 4) │ ├── ch01-intro.md │ ├── ch02-body.md │ └── ... ├── cover.jpg ← Cover image (Phase 4.5) └── Book-Output/ ← Generated output (Phase 5) ├── {slug}.html ← Complete book HTML └── {slug}.pdf ← Print-ready PDF ``` > **⚠️ Original chapter files are NEVER deleted.** Chapters remain in `chapters/` for > future editing, repurposing, or re-merging with different settings. Only the merged > HTML/PDF is added to `Book-Output/`. --- ## Five-Phase Workflow --- ### Phase 1: Topic Selection & Project Setup **Goal:** Confirm the book idea, create the project directory and config file. #### Step 1.1 — Identify or Create Book Ask the user: - "What book do you want to write? Give me a working title, the target reader, and the core problem the book addresses." - If a list of existing book projects exists (e.g., `book-writing-projects.md`), show it and ask them to choose. Collect: | Field | Required | Example | |-------|----------|---------| | Working title | ✅ | *The Anxiety That's Invisible to Everyone Else* | | Subtitle | ❌ | *A Guide for High-Functioning People* | | Author name | ✅ | Daniel Du | | Target reader | ✅ | Professionals aged 30-50 with anxiety they hide well | | Core topic/problem | ✅ | High-functioning anxiety masking deeper exhaustion | | Book type | ✅ | `self-help` or `health-guide` (affects KDP description template) | | Publisher name | ❌ | Name for KDP publisher field | | KDP Select | ❌ | `true` for exclusive Amazon (default: `false`) | #### Step 1.2 — Generate Book Slug Convert title to a URL-safe slug: ``` "The Anxiety That's Invisible to Everyone Else" → "the-anxiety-thats-invisible-to-everyone-else" ``` #### Step 1.3 — Initialize Project Run the setup script: ```bash python3 {skill_dir}/scripts/setup-book.py --book {slug-keyword} ``` Or create files manually: 1. Create `{project_path}/chapters/` directory 2. Create `{project_path}/Book-Output/` directory 3. Create `book-config.json` (see format below) 4. Create `outline.md` with chapter titles #### Output: `book-config.json` ```json { "workspace": ".", "chapters_dir": "chapters", "output_dir": "Book-Output", "cover_image": "", "chapters": [ "ch01-introduction.md", "ch02-understanding.md", "ch03-strategies.md", "appendix.md" ], "title": "Book Title", "subtitle": "Subtitle", "author": "Author Name", "topic": "core topic or problem the book addresses", "target_audience": "who this book is for", "book_type": "self-help", "description": "one-line description", "hook": "opening hook for KDP description (optional, auto-generated if omitted)", "publisher": "publisher name (optional)", "kdp_select": false, "categories": [], "toc_items": [ "Introduction", "Understanding the Problem", "Practical Strategies", "Appendix" ], "slug": "book-slug" } ``` --- ### Phase 2: Content Outline **Goal:** Plan the full chapter structure before writing begins. **Read reference:** `references/writing-style.md` for chapter structure guidance. Create `outline.md` with: ```markdown # {Book Title} — Content Outline **Subtitle:** {subtitle} **Author:** {author} **Target Reader:** {target audience} **Word Count Target:** 8,000–12,000 words (8-10 chapters + appendix) ## Chapter 1: {Title} - Key point 1 - Key point 2 - Key point 3 - **Target:** 800-1,200 words ## Chapter 2: {Title} ... ## Appendix: Resources & Next Steps - Resource list - Glossary - **Target:** 600-800 words ``` **Key decisions to make with the user:** - Total number of chapters (recommend 8-10 + appendix) - Chapter sequence and flow - Whether to include an appendix --- ### Phase 3: KDP Metadata Generation **Goal:** Generate publishing-ready metadata for Amazon KDP before the book is finalized. **Read reference:** `references/kdp-metadata.md` for full KDP field specifications. Run the generation script: ```bash python3 {skill_dir}/scripts/generate-kdp-metadata.py --project {project_path} ``` For full interactive editing: ```bash python3 {skill_dir}/scripts/generate-kdp-metadata.py --project {project_path} --interactive ``` #### What Gets Generated (`kdp-metadata.json`) | Field | Source | Notes | |-------|--------|-------| | `title` | `book-config.json` | | | `subtitle` | `book-config.json` | Title + Subtitle < 200 chars | | `author` | `book-config.json` | | | `description.html` | Auto-generated | ≤4,000 chars, HTML-formatted | | `keywords` | Auto-generated | Up to 7, KDP-compliant | | `categories` | `book-config.json` | Up to 3 | | `language` | `book-config.json` | Default: English | | `validation` | Script check | Errors, character counts, prohibited content | #### Description Auto-Generation The script uses templates based on `book_type`: - `self-help` → Hook → bullet points of what the book offers → who it's for - `health-guide` → "The book your doctor didn't give you" → medical topic angle - Default → flexible template **Hook auto-detection** for common topics: - Perimenopause, Anxiety, Burnout, Long COVID, Chronic Illness, Caregiver - If the book topic matches, a compelling opening hook is auto-generated **Keyword auto-generation** based on: - Title keywords (perimenopause, anxiety, burnout, etc.) - Format keywords (self-help book, practical guide, evidence-based) - Audience keywords (women's health, workplace wellness, etc.) #### Manual Review Required The user **must review** before publishing: 1. Title and subtitle for accuracy 2. HTML description — verify tone, accuracy, and length 3. Keywords — swap in/out to match competitive titles on Amazon 4. Categories — choose 2-3 from Amazon's category browser --- ### Phase 4: Content Writing **Goal:** Write each chapter following the style guide. **Read reference:** `references/writing-style.md` for full writing instructions. #### Per-Chapter Structure ```markdown # Chapter X: {Chapter Title} {Opening hook — 2-3 paragraphs, specific scenario or question. No definitions, no statistics openers. Grab them immediately.} ## {Section Heading} {Short paragraphs, concrete examples, evidence-based claims. Grade 7 reading level. Active voice. No filler phrases.} ### {Sub-section if needed} {Detailed content broken into digestible pieces} > **Key Takeaway:** {One clear, memorable sentence. This IS the chapter.} **Chapter Summary:** {2-3 sentences recapping what was covered. No new information.} **What to do this week:** 1. {Specific, actionable step — something a tired person can actually do} 2. {Same format} 3. {3-5 items max} ``` #### Writing Approach **Single chapter:** Write one chapter, save to `chapters/ch{XX}-{slug}.md`, update `book-config.json` chapters list. **Multiple chapters (8+):** Use parallel agents (agent teams or subagents) to write chapters simultaneously, then review and merge. #### After Writing Each Chapter 1. Save chapter file to `chapters/` 2. Update `book-config.json` — add chapter to `chapters` list and `toc_items` 3. Update `outline.md` — mark chapter as complete 4. Notify user of completion #### Word Count Targets | Element | Words | |---------|-------| | Main chapter | 800–1,200 | | Appendix | 600–800 | | Opening hook | 60–120 | | Key Takeaway | 15–25 | | Each action item | 10–25 | --- ### Phase 4.5: Cover Design **Goal:** Generate a professional book cover based on the content outline and KDP metadata. **Read reference:** `outline.md` and `kdp-metadata.json` to understand the book's theme, audience, and tone. #### Step 4.5.1 — Prepare Design Brief Based on `outline.md`, identify: - **Book tone:** Inspirational, clinical, urgent, calming? - **Target reader:** Age range, professional context, emotional state - **Visual metaphors:** What imagery best represents the core problem/solution? - **Color palette:** Warm/cool tones, high-energy/soothing? #### Step 4.5.2 — Generate Cover Image Use an image generation agent or tool with this prompt: ``` 你是非常资深的畅销书封面设计师，熟悉亚马逊书店、纽约时报畅销书的封面设计的设计思想和设计风格。 请根据以下信息设计图书封面： **书名：** {title} **副标题：** {subtitle} **目标读者：** {target_audience} **核心主题：** {topic} **书籍类型：** {book_type} **设计要求：** 1. 封面需传达书籍的核心主题和情感基调 2. 适合目标读者的审美偏好 3. 在亚马逊书店的缩略图尺寸下依然清晰可辨 4. 专业、畅销书级别的视觉品质 5. 输出格式：JPG 请直接生成封面图片并保存到项目目录。 ``` > **Tip:** For AI image generation, use `baoyu-image-gen` skill or similar tool with this prompt. Save the output as `cover.jpg` in the project root. #### Step 4.5.3 — Update book-config.json After generating the cover, update `book-config.json`: ```json { "cover_image": "cover.jpg" } ``` > **Note:** The cover image should be high-resolution (at least 300 DPI for print, minimum 2500×2500 pixels for Amazon KDP requirements). --- ### Phase 5: Merge to Book (HTML + PDF) **Goal:** Combine all chapters and cover into a complete formatted book. **Step 5.1 — Verify Configuration** Confirm `book-config.json` has: - All chapters listed in `chapters` (correct filenames, correct order) - All titles in `toc_items` (matching chapters list 1:1) - `title`, `subtitle`, `author`, `description` filled in **Step 5.2 — Run Merge Script** ```bash python3 {skill_dir}/scripts/merge-book.py --project {project_path} ``` The script: 1. Reads `book-config.json` from `{project_path}` 2. Loads all Markdown chapter files from `chapters/` 3. Converts Markdown to HTML (supports tables, lists, blockquotes, code blocks, headings) 4. Builds full HTML document: Cover → Description → TOC → Chapters → Back Cover 5. Generates A4 PDF via Playwright (if installed) **Step 5.3 — Verify Output** - Open `{project_path}/Book-Output/{slug}.html` in browser — check formatting - Check `{project_path}/Book-Output/{slug}.pdf` (if generated) — check pagination **Output files:** | File | Location | |------|----------| | Complete HTML book | `{project_path}/Book-Output/{slug}.html` | | Print-ready PDF | `{project_path}/Book-Output/{slug}.pdf` | | Original chapter files | `{project_path}/chapters/*.md` ← **Never deleted** | | KDP metadata | `{project_path}/kdp-metadata.json` | --- ## Scripts Reference All scripts live in `{skill_dir}/scripts/` and require only Python 3 standard library (except `merge-book.py` which optionally uses `playwright` for PDF). | Script | Purpose | Key Usage | |--------|---------|-----------|