📚 KindlePub

An end-to-end Amazon KDP self-publishing pipeline, packaged as a portable Agent Skill.

Take a finished manuscript all the way onto Amazon — an epubcheck-clean Kindle EPUB, a cover whose art you generate with Gemini Nano Banana and assemble in KDP Cover Creator (which auto-sizes the spine — no custom PDFs), drafted KDP metadata, and a field-by-field walk through KDP's Details → Content → Pricing → Publish flow for the ebook, paperback, and hardcover.

Why

Shipping a book to KDP is a maze of format gotchas: an EPUB that silently fails epubcheck, a cover rejected because the spine is off, garbled AI text smeared across the art. KindlePub encodes the hard-won fixes so your agent gets it right the first time — and because it's a standard SKILL.md, it travels with you across Claude Code, Codex, Cursor, Gemini CLI, and the Claude app instead of being trapped in one tool.

Build everything to the edge; the human enters credentials, operates native file pickers, and presses Publish. The skill never types your passwords.

What it does

Phase	Output
1	Lock the manuscript, export a clean DOCX (no copy/paste loss)
2	Reflowable Kindle EPUB, `epubcheck`-clean (encodes 3 ebooklib traps that waste hours)
3	Cover — generate art with Gemini Nano Banana, assemble in KDP Cover Creator (it adds the title and auto-sizes the spine; reuse the front for the ebook)
4	Print — upload the manuscript DOCX; KDP paginates it and Cover Creator sizes the spine (no custom PDF)
5	Drafted KDP metadata (description, BISAC categories, keywords, AI-content answers, pricing)
6	Field-by-field KDP walkthrough (DRM, KDP Select, pre-order, the hardcover print-cost trap)
7	A saved publication record so the next format and next book go faster

Install

Any coding agent (via the openskills loader):

git clone https://github.com/jessl2juice/kindlepub
npx openskills install ./kindlepub      # installs into Claude Code, Codex, Cursor, Gemini CLI…

Claude app / Cowork: download kindlepub.skill from Releases and click Save skill.

Manual (any SKILL.md-aware tool): copy this folder to .claude/skills/kindlepub/.

Requirements

Python 3, plus pip deps for the EPUB build:

pip install mammoth ebooklib beautifulsoup4 lxml epubcheck

epubcheck also needs Java on your PATH. (The cover and spine are done in KDP Cover Creator — no extra image/PDF libraries needed.)

Usage

Just talk to your agent — "I finished my manuscript, help me put it on Amazon" — and the skill drives the pipeline, handing you each irreversible click. The two scripts build and validate the Kindle EPUB; the cover is generated in Nano Banana and assembled in KDP Cover Creator (in the browser).

python3 scripts/build_epub.py            # -> book.epub  (edit the CONFIG block first)
python3 scripts/validate_epub.py book.epub
# Cover: generate art with Nano Banana (see references/), then build it in KDP Cover Creator.

What's inside

kindlepub/
├── SKILL.md                              # the skill: when to trigger + the 7-phase procedure
├── scripts/
│   ├── build_epub.py                     # DOCX -> epubcheck-clean reflowable EPUB
│   └── validate_epub.py                  # epubcheck wrapper (the same check KDP runs)
└── references/
    ├── kdp-walkthrough.md                # field-by-field KDP script + Cover Creator steps
    ├── metadata-template.md              # the metadata you fill in
    └── nanobanana-cover-prompts.md       # cover-art prompt recipes + the no-text rule

Why it's better than winging it

The EPUB actually validates. The build script encodes three ebooklib traps (the encoding-declaration empty-body bug, add_link CSS attachment, and the set_cover / OPF-096 page-list crash) that silently produce broken-but-"valid"-looking books.
The cover looks human. AI models always sneak garbled text onto pennants, clothing, spines, and screens — so the Nano Banana prompts forbid text on those surfaces and KDP Cover Creator lays the real title in afterward.
The spine fits with zero math. KDP paginates your manuscript and Cover Creator auto-sizes the spine to that page count — no guessed spine, no custom cover PDF, no rejected upload.

Contributing

PRs welcome — see CONTRIBUTING.md. The bar: keep it generic and secret-free, keep the SKILL.md frontmatter valid, and preserve the hard-won notes (they exist because something broke once).

License

MIT — use it, fork it, ship your book.

Acknowledgements

Built on the open Agent Skills standard (SKILL.md), originated by Anthropic and now read by ~40 agent tools. Part of the Open Skills idea: the way you work should be yours and portable, not rented back to you by whichever AI app you happened to use.

Kindlepub

README