book-converter

# Book Converter Skill

Convert EPUB books into professionally formatted Markdown books with AI-assisted quality improvements.

## Overview

This skill converts EPUB files into high-quality Markdown documents by:

1. Using pandoc to extract raw Markdown from EPUB
2. Creating a structured project directory
3. Planning and executing AI-driven formatting fixes
4. Producing chapter-by-chapter formatted output
5. Generating merged book file with Table of Contents

## Quick Start

User provides an EPUB file path:

```
/Users/username/Downloads/Book.Name.2024.epub
```

Execute the conversion workflow:

```bash
python3 scripts/convert_book.py "/path/to/book.epub"
```

This initiates the complete conversion process.

## Workflow

**CRITICAL: Use subagents for all formatting work to avoid polluting main context.**

### Phase 1: Setup and Extraction (Main Agent)

Run the conversion script:

```bash
python3 scripts/convert_book.py "/path/to/book.epub"
```

This script:
1. Verifies EPUB file exists
2. Creates project structure:
   - `books/book-name/` - Main directory
   - `books/book-name/raw/` - Pandoc output
   - `books/book-name/chapters/` - Formatted chapters
   - `books/book-name/images/` - Extracted images
3. Runs pandoc to extract Markdown
4. Copies formatting standards to project directory

**Output**: Raw Markdown in `books/book-name/raw/book-parsed.md`

### Phase 2: Analysis and Planning (Script + Subagent)

**Step 1**: Run the structure analysis script (Main Agent):

```bash
python3 books/book-name/analyze_structure.py books/book-name
```

This script:
- Extracts all headers with line numbers
- Detects formatting issues by sampling
- Suggests chapter boundaries
- Creates `STRUCTURE_ANALYSIS.md` report (~5-10 KB instead of 35k+ lines)

**Step 2**: Launch a **general** subagent to create mapping files:

```python
Task(
  subagent_type="general",
  description="Create chapter map and formatting plan",
  prompt="""Create CHAPTER_MAP.md and FORMATTING_PLAN.md:

1. Read bo