best-selling-book-writer

name	best-selling-book-writer
description	Complete AI-powered book writing & self-publishing workflow: topic selection → content outline → chapter writing → cover design → Amazon KDP metadata → formatted HTML/PDF. Designed to produce best-selling self-help and health books. Platform-agnostic — usable in any AI agent with file system access (WorkBuddy, Claude Code, Codex, OpenClaw, Hermes, etc.). No agent-specific dependencies; only Python 3 + optional Playwright for PDF generation.
agent_created	true

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:

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

{
  "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:

# {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:

python3 {skill_dir}/scripts/generate-kdp-metadata.py --project {project_path}

For full interactive editing:

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

# 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:

{
  "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

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
setup-book.py	Create new book project	python3 setup-book.py --book {keyword}
generate-kdp-metadata.py	Generate KDP publish metadata	python3 generate-kdp-metadata.py --project {path}
merge-book.py	Merge chapters → HTML + PDF	python3 merge-book.py --project {path}

Config Auto-Discovery

All scripts auto-discover book-config.json in this priority order:

1. --config /path/to/config.json (explicit flag)
2. --project /path/to/project/ (explicit flag, looks for config inside)
3. ./book-config.json (current working directory)
4. .workbuddy/book-projects/*/book-config.json (common pattern)
5. Script's own directory (skill-level config)

Playwright for PDF (Optional)

If playwright is not installed, merge-book.py still generates the HTML. To enable PDF:

pip install playwright && playwright install chromium

---

KDP Publishing Checklist

Before publishing on Amazon KDP:

• Review kdp-metadata.json — title, subtitle, author
• Copy description.html to KDP description field (≤4,000 chars including HTML tags)
• Enter 7 keywords (no quotes, no duplicates, no promotional language)
• Select up to 3 relevant Amazon categories
• Set language and primary marketplace
• Upload cover image — ensure cover.jpg meets Amazon's specifications (minimum 2500×2500 px, 300 DPI)
• Review print book interior — confirm ISBN if using print
• Set pricing and rights (KDP Select: exclusive or non-exclusive)
• Preview book in KDP's online previewer before publishing

---

Skill File Map

best-selling-book-writer/
├── SKILL.md                          ← AI agent instructions (this file)
├── scripts/
│   ├── setup-book.py                 ← Phase 1: Project initialization
│   ├── generate-kdp-metadata.py      ← Phase 3: KDP publishing metadata
│   └── merge-book.py                 ← Phase 5: HTML + PDF generation
└── references/
    ├── kdp-metadata.md               ← Amazon KDP field specs & rules
    └── writing-style.md              ← Chapter writing guidelines

Workflow order: Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 4.5 → Phase 5