---
name: epub_ebook_craft
description: Turn drafts, manuscripts, and chapter files into professional, validation-passing EPUB 3 ebooks. Builds the package correctly (container, OPF metadata, TOC, spine), styles conservatively for Kindle, Apple Books, and Kobo, audits the result, and maps each distributor's upload specs. Triggers when the user asks to make, fix, convert, audit, or publish an ebook or EPUB.
---

# EPUB Ebook Craft

## Purpose
Take a manuscript from draft to a professional EPUB 3 file that passes epubcheck with zero errors and meets the upload specs of the major distributors (KDP, Apple Books, Kobo, Draft2Digital). Covers the full pipeline: source prep, package construction, metadata, navigation and TOC, styling, validation, and the distributor gate checklist.

## Workflow
1. **Prep the source.** Clean paragraph and heading styles first. One style per purpose (Heading 1 for chapters, Heading 2/3 for sections, Normal for body). Strip manual spacing, tab indents, headers, footers, and page numbers. Chapter breaks between chapters. Images as JPG or PNG, inline, with captions as plain text. A clean source converts cleanly; a dirty one never does.
2. **Build the package.** Do not hand-write the ZIP. Use `scripts/epub_build.py` with a manifest (copy `assets/manifest-template.json`):
   ```
   python3 scripts/epub_build.py manifest.json -o book.epub --assets ./assets
   ```
   Chapters can be `.md` (converted by a conservative mini-markdown: headings, bold, italic, lists, quotes, images) or `.xhtml` (used as-is). The builder emits title page, copyright page, cover page, nav TOC with landmarks, a reader-safe stylesheet, and a correctly ordered container (mimetype first, stored uncompressed). See `references/epub3-package.md` if you need to hand-edit a package.
3. **Style conservatively.** The shipped CSS uses the EPUB 3.3 guaranteed subset (CSS 2.1 plus Fonts 3, Text 3, Writing Modes 3, Text Decoration 3). Keep it that way. Two font families max; readers override fonts anyway. Details in `references/safe-css.md`.
4. **Validate twice.** First the fast local pre-flight (no Java):
   ```
   python3 scripts/epub_audit.py book.epub
   ```
   Then the real epubcheck (the official W3C/DAISY conformance checker). Java-free route:
   ```
   npx epubcheck-standalone-cli book.epub
   ```
   Or the official jar: `java -jar epubcheck.jar book.epub`. Zero errors is the bar. Fix warnings when cheap. Common error codes and fixes live in `references/validation.md`.
5. **Gate against the distributor.** `references/distributor-specs.md` holds the per-platform checklist: cover dimensions, file limits, metadata matching rules, TOC requirements. Title and author must match the cover, the title page, and the store metadata exactly, character for character.

## Output Contract
A finished EPUB must satisfy all of these:
- Passes epubcheck with 0 errors (warnings reviewed, not ignored).
- `mimetype` is the first ZIP entry, stored uncompressed, exactly `application/epub+zip`.
- OPF carries `dc:identifier` (matching `unique-identifier`), `dc:title`, `dc:language`, and `dcterms:modified` as `YYYY-MM-DDTHH:MM:SSZ`.
- Exactly one nav document (`properties="nav"`) with a working, hyperlinked TOC; every link resolves; landmarks point at spine items.
- Every resource is listed in the manifest with a correct media type; the spine is in reading order; the cover image carries `properties="cover-image"`.
- Reflowable layout, unless the book is a picture book, cookbook, or comic.
- Cover meets the target distributor's dimensions and sits first in the book.

## Operating Rules
- Never invent a spec number. Cover sizes, file limits, royalty rules, and metadata requirements come from `references/distributor-specs.md`. If a number is not there, look it up from the distributor's own docs. Do not guess.
- The TOC is the top rejection reason on KDP. Every chapter linked, every link resolving, clicked end to end. No exceptions.
- Reflowable by default. Fixed layout only for picture books, cookbooks, and comics, and only when you know the platform accepts it.
- Never hand-build the ZIP container. The mimetype-first-uncompressed rule kills more hand-built EPUBs than anything else. Use the builder or a proven toolchain.
- PDF is the worst conversion source. If only a PDF exists, say so plainly and expect reflow damage; do not promise a clean result.
- Accessibility metadata (`schema:accessibilitySummary` and friends) is increasingly required by stores. Add it when publishing to retail; the fields are listed in `references/distributor-specs.md`.
- After any conversion (pandoc, Calibre, Kindle Create), always re-validate. Converters introduce their own epubcheck errors; fix them, do not ship them.
- Style law for everything this skill generates: no em dashes, plain direct prose, no filler.