--- name: jessl2juice/kindlepub source: https://app.decimal.ai/s/jessl2juice-kindlepub@1/SKILL.md source_sha256: a61919bd4c2c --- # KindlePub — Amazon KDP publishing pipeline Take a finished manuscript all the way onto Amazon. Each format (Kindle ebook, paperback, hardcover) is a SEPARATE KDP title that KDP links on one product page. The Kindle ebook is the fast win; the paperback is the value-priced print edition; the hardcover is the premium edition. You can do one, two, or all three. Build everything to the edge, then hand the user the irreversible clicks. The user enters credentials, operates native file pickers, sets anything permanent, and presses Publish. You never type passwords or drive an OS file-open dialog. **Cover approach (important):** generate the cover ART with Gemini Nano Banana, then assemble the actual cover in **KDP Cover Creator** — it lays in the title/author typography and auto-sizes the spine to the page count. Do **not** build a custom print-cover PDF or a custom 6×9 interior PDF; let KDP's tools size and paginate. (This is the path that shipped.) ## What you need from the user (gather first) - The FINAL manuscript source. A Google Doc is ideal; a .docx also works. Confirm it is truly final — filenames lag content, so open it and read the version stamp (a "v15.7 FINAL" doc beats a "v16 draft" with a higher number). - Title, subtitle, author name, and the imprint/publisher line. - Cover art or a cover concept. If they have brand art, great; if not, you will generate it with Nano Banana (see Phase 3). - Which formats they want, and their KDP account email. Flag early: the KDP account needs **Two-Step Verification + tax/banking** complete before the final Publish and before any royalty payment. That is the user's to finish. ## Phase 1 — Lock the source, export a clean DOCX If the source is a Google Doc, export a clean DOCX through the logged-in browser by navigating to: `https://docs.google.com/document/d//export?format=docx`. This downloads the .docx with no copy/paste loss. Stage it for the EPUB build and (for print) for upload to KDP. ## Phase 2 — Build the Kindle EPUB Use `scripts/build_epub.py`. Edit the CONFIG block at the top (input DOCX, title, subtitle, author, contributors, cover JPG path, publisher) and run it. It uses `mammoth` (DOCX->HTML) + `ebooklib`, segments chapters, and adds the front matter most manuscripts lack: a copyright page, a medical/crisis disclaimer (the 988 block — keep it for anything touching health or safety), and a navigable table of contents. It preserves in-text diagrams. Then validate with `scripts/validate_epub.py` (wraps `epubcheck`, which needs Java). Ship only on a clean pass. The script already encodes the three ebooklib traps that cost real time the first time: - Set `EpubHtml.content` to HTML with NO `` declaration. ebooklib's lxml path silently returns an EMPTY body on an encoding-declared Unicode string, so your pages come out 0 bytes and "valid." - Attach CSS with `add_link(...)`, not a `` in your own head — ebooklib rebuilds the head from the title + links you register. - After `set_cover(create_page=True)`, set the cover page `is_linear=True` and pass `write_epub(..., {'epub3_pages': False})`, or epubcheck throws OPF-096 / the page-list generator crashes on the empty cover body. ## Phase 3 — The cover: Nano Banana art → KDP Cover Creator Generate the cover **art** with Nano Banana (Gemini's image model), then assemble the cover in **KDP Cover Creator**. Cover Creator adds the title/author typography and auto-sizes the spine to the page count, so there is no custom PDF and no manual spine math. Read `references/nanobanana-cover-prompts.md` for the prompt recipes and the one rule that matters: AI models always sneak garbled text onto pennants, clothing, book spines, and screens, so the prompt must forbid text on those surfaces — Cover Creator adds the real title later. The flow: 1. Give the user the prompt (and tell them which reference image to attach). They generate the art in Nano Banana / Gemini and send back the file (no text in the art). 2. In KDP, open **Cover Creator**, upload that art, and let it lay in the title, subtitle, and author and size the spine + back automatically. Uncheck "my cover has a barcode" so KDP leaves room for its own. Iterate on the layout with the user. 3. For the **Kindle ebook** front cover, use Cover Creator's front-cover image (download it) as the ~1600x2560 JPG you upload in the ebook Content step — same art, one cover everywhere. (Do NOT build a custom wraparound print-cover PDF — Cover Creator is the path.) ## Phase 4 — Print interior (paperback / hardcover) — no custom PDF Do **not** build a 6×9 interior PDF. Upload the **manuscript DOCX** to KDP for the print title; KDP paginates it, and Cover Creator sizes the spine to the resulting page count. Pick **Black & white** interior for a text book (see the print-cost trap in the walkthrough) and the common **6×9** trim. Let KDP's tools handle pagination and the spine. ## Phase 5 — Draft the KDP metadata Fill in `references/metadata-template.md`: title, subtitle, author, the back-cover-style description (KDP allows light HTML — paste clean

paragraphs via the Description box's "Source" mode), 3 BISAC categories, 7 keywords, the AI-content answers, price, and the release plan. Reuse the description as the online blurb and a trimmed version on the back cover. ## Phase 6 — Walk the user through KDP Drive the browser through Details -> Content -> Pricing -> Publish. Read `references/kdp-walkthrough.md` for the field-by-field script and every decision (AI-content disclosure, DRM, KDP Select, pre-order dates, the Cover Creator steps, and the print-cost trap that quietly forces a ~$49.99 hardcover). Hand the user every native file picker and the final Publish click. ## Phase 7 — Document it When the book is set up, save a publication record to the user's knowledge base (every KDP book id, the locked blurb + back-cover copy, asset locations, pricing, the AI disclosures, release dates) so the next format and the next book go faster. If the user keeps a notes repo, write it there and commit. ## The scripts are templates, not black boxes The two EPUB scripts each have a CONFIG block at the top — edit it for the book at hand. They are the exact tools that shipped a real title; read them before running so you can adapt rather than fight them. The cover and print spine are done in KDP's own tools (Cover Creator), not in code. ## Tools & adapters | Capability | Claude Code / Cowork | Codex / Cursor / other | |------------|----------------------|------------------------| | Build EPUB | bash + `python3 scripts/build_epub.py` (pip deps) | same | | Validate EPUB | `python3 scripts/validate_epub.py` (epubcheck + Java) | same | | Generate cover art | hand user the Nano Banana / Gemini prompt | same | | Assemble cover + spine | KDP **Cover Creator** in the browser | same | | Drive KDP / native pickers | hand the user the irreversible clicks | same | Deps: `mammoth ebooklib beautifulsoup4 lxml epubcheck` (+ Java on PATH for epubcheck). ## Portability Class: **portable**. A self-contained pipeline with no external coupling and no secrets — the only dependencies are pip packages plus Java for epubcheck, and there is no env config (`requires_config: []`). The cover and spine are assembled in KDP Cover Creator (no custom PDF), and the worked example in `references/nanobanana-cover-prompts.md` is fully generic (no real book or author names). The installed original remains the untouched fallback until this copy is validated at parity. ## Acceptance check - Trigger: "put my book on Amazon" / "make this a Kindle book" / "I finished my manuscript, now what". - Expect: builds an epubcheck-clean EPUB; generates cover art with Nano Banana (no garbled text); assembles the cover in KDP Cover Creator (auto-spine) and reuses its front for the ebook; uploads the manuscript DOCX for print; drafts KDP metadata; walks Details→Content→Pricing→Publish, handing the user every irreversible click. - Must NOT: type the user's passwords or drive native OS file pickers; ship an EPUB that fails epubcheck; build a custom print-cover or 6×9 interior PDF (use Cover Creator