A Claude Code skill · the book-production shelf

The EPUB passed its validator. It had 1 of its PDF’s 22 images.

A valid file and a complete file are different things. This skill counts what every format of a finished book actually carries, checks the pixels and alt text inside it, and converts to formats beyond the usual six. It never touches the prose.

Three jobs, three files

Each opens only when the request needs it. Each rule inside is tagged with the incident, the dated vendor page, or the word SPECULATIVE.

JOB 1

Interior images

Inventory every image, decide informative or decorative, check pixels against print and ebook, and record what a full-bleed image becomes when the layout changes.

JOB 2

Conversion

Which formats beyond the six-file set a book needs, and how to make each from one master. The shelf run found the final-set EPUB carrying 1 image, and the Markdown master it most likely came from has none to give it (inferred, not recorded).

JOB 3

Cross-format check

The same images in the same order with the same alt text, each format passed by its real checker. Validity and census, side by side, every time.

Real output, real book

The shipped set for Are You Actually Hungry? (files dated 2026-06-15), checked 2026-09-26. The book is the operator's own. Paths shortened.

epubcheck 5.4.0 → shipped EPUB0 errors
Validating using EPUB version 3.4 rules.
No errors or warnings detected.
Messages: 0 fatals / 0 errors / 0 warnings / 0 infos
format-census.py → shipped setexit 1
format        raster  vector  refs   alt d/e/m  notes
HTML source       14      75    89      1/13/0
PDF               22     n/a   n/a         n/a  min 267 ppi; colour gray,rgb
EPUB               1       0     1       0/0/0
DOCX               0       0     0       0/0/0

order check: source 14 vs EPUB 1
  DIFFERS: 13 source image(s) absent from EPUB
FAIL: EPUB 1 raster vs PDF 22 · DOCX 0 raster vs PDF 22

The same source, converted again with five source-side fixes, into a scratch folder. The shipped files were not touched.

epubcheck → rebuilt EPUB0 errors
format        raster  vector  refs   alt d/e/m
HTML source       18      75    93     17/17/0
PDF               22     n/a   n/a         n/a
EPUB              18      20    93     17/76/0
DOCX              34      20    93     17/76/0

order check: source 18 vs EPUB 18
  same images, same order.
Counts and order agree. Not checked: how it reads on a device.
Shipped EPUBRebuilt EPUB
epubcheck0 errors0 errors
Raster images1 (the cover)18, source order
Figures with alt text016, the author's own labels
Size2.9 MB7.2 MB (interior images capped at 1200×1800)

The rebuild shows the images can survive; it is not a drop-in replacement, because the print HTML it came from is a different edition of the text. For a book that is already live, the fix is inserting the images into the shipped file: 0 words changed, checked by a flattened-text diff.

A second real book, BikYasa Yoga, fails the other way: its EPUB has 124 images against 121 in its PDF (and 108 in its DOCX; whether they are the same images was not tested) and fails epubcheck with 157 errors, 124 of them images missing the required alt. A validator and a count answer different questions.

How a rule earns its place

The skill states what happened before it states what to do.

INCIDENT A dated event on the real shelf, with its file. Example: page 7 of the same PDF has every page box equal to the trim box, so a full-bleed photo extends nowhere past the edge.

VENDOR A retailer's page, fetched and dated. Apple's guide recommends about 10 MB of un-encoded image data per XHTML file; one of this book's 1800×2700 openers is 14.6 MB by that arithmetic.

SPECULATIVE No incident, no cite. Figure numbering, large print, a second print vendor: nothing on the shelf has needed them, so nothing here states them as fact.

Where a vendor page could not be opened (Kobo's returned HTTP 403), the entry says NOT OPENED and gives the operator the step.

Proof

The run above is the only evidence this page carries: one shipped book measured, one rebuilt and re-validated. There are no testimonials or usage figures yet.

Setup

  1. Clone the repo, or point a Claude Code session at the folder. SKILL.md triggers on requests like "do the formats match?" and "why is my EPUB missing the pictures?".
  2. Install epubcheck (brew install epubcheck) and poppler (pdfimages) for the PDF column.
  3. Run the census on a finished set: python3 tools/format-census.py --pdf book.pdf --epub book.epub --docx book.docx. Add --html source.html --src-dir <dir> to test image order.
  4. Read the result next to the validator's, and fix at the source, never in one output.

FAQ

Does it edit my book?

No. It never rewrites, trims or corrects prose. It also does not write alt text or captions for you; it lists the images that need them and asks the author.

Does it rebuild the print PDF or the six-file package?

No. That is Publishing Preparation. This skill takes its output and the source as input. A defect in the six-file EPUB or DOCX is reported here and fixed there.

Does a passing census mean the book is fine?

No. Counts and byte order are a tripwire. The PDF's image order is not tested, and neither is placement or how the file reads on a device. Open a page of each format that has a full-bleed or floated image.

Are the retailer numbers current?

They are dated the day they were fetched, and no vendor page showed a revision date. Re-open the page before relying on a number for a title.

What is out of scope?

Cover design, title and jacket copy, audio, video, fixed-layout children's books, vendor accounts and uploads.