epub_ebook_craft v1.0.0

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.

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

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