# Best Selling Book Writer

> 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.

- Skill: `duchangyu/best-selling-book-writer` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add duchangyu/best-selling-book-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/duchangyu/best-selling-book-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: duchangyu (https://skillmd.com/u/duchangyu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/duchangyu/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 |
|--------|---------|-----------|
| `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:
```bash
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
```