agentleFS
hfadhlullahhfadhlullah/kaizen/skills/media/kaizen-book/SKILL.md

kaizen-book

Skill6 starsChanged 45 days agoMITView on GitHub

Write, proofread and publish a book. Interviews the author first (kind of book, genre such as sci-fi, romance, fantasy, thriller, memoir or non-fiction, readers, language, length, voice, look), then outlines and drafts it chapter by chapter with a style sheet, proofreads with a numbered change list, and builds a single-file offline e-book that reads like a real book (cover that opens, page-flip, paper, themes, font size, resume), an A5 colour print PDF, a black-and-white print PDF, optional volume PDFs, and a website folder with WhatsApp/social link previews. Use when the user wants to write a book, novel, novella, memoir or story collection, turn a manuscript (Markdown or .docx) into an e-book or printable PDF, proofread a manuscript, or publish a book online.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run every script from the project folder.

    line 29
  2. Very specific:

    Follow references/writing.md: the outline, approved.

    line 45
  3. Very specific:

    Follow references/proofread.md.

    line 50
  4. Distinctive:

    Look at the screenshots yourself, and show the cover and one spread to the author.

    line 62
  5. Very specific:

    Look at the PDF pages before handing them over (pdftoppm -r 40 -png output/book.pdf /tmp/p then a contact sheet): the cover, the contents, …

    line 65

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Kaizen book

A book lives in book/ in the user's project folder, and everything it produces goes to output/:

book/
  brief.md        interview answers, approved by the author
  outline.md      chapter plan, approved by the author
  style.md        style sheet: names, spellings, voice rules, facts so far
  manuscript.md   the text (# Part, ## Chapter | subtitle, ### Section, [^1] footnotes)
  book.json       title, author, lang, style, cover, url, volumes…
  images/         cover and figures
  proofread.md    numbered change list, marked applied / declined
output/
  book.html       the e-book: one file, works offline
  book.pdf        A5 colour print
  book-mono.pdf   A5 black and white (white typeset cover, greyscale images and emoji)
  book-vol-N.pdf  one per volume, black and white (or colour), continuous page numbers
  og.jpg          1200×630 link-preview image
  shots/          screenshots from verify.mjs
  deploy/         static site: index.html (preview loader), reader.html, PDFs, og.jpg

Run every script from the project folder. S=<this skill>/scripts. Worked example: examples/.

0. Setup, once per machine

$S/check.sh lists what is missing (python3, node, poppler's pdfinfo, Playwright). $S/setup.sh installs Playwright 1.62.1 and Chromium into ~/.kaizen/kaizen-book (override with KAIZEN_BOOK_HOME), which is about 150 MB. Tell the user before you run it. Building the HTML needs only python3. PDFs and screenshots need the rest.

1. Where to start

  • A new book: interview first. Read references/interview.md and follow it. Nothing is written until brief.md is approved.
  • An existing manuscript (.md, .docx, pasted text): convert it as described at the end of references/writing.md, write book.json, and go to step 3. Ask only what book.json needs (title, author, language, style, cover, url).
  • A revision of a built book: change manuscript.md, then repeat steps 3–5. Never hand-edit output/.

2. Write

Follow references/writing.md: the outline, approved; the style sheet; chapters in batches of three to five, with a stop for the author after each batch. Never invent facts, sources or quotes. Mark open questions [[CHECK: …]].

3. Proofread

Follow references/proofread.md. Run python3 $S/check_book.py book for structure, then write book/proofread.md as a numbered change list. Apply only the numbers the author accepts. The build does not go ahead while check_book.py reports errors.

4. Build and look

python3 $S/build_book.py book            # → output/book.html (fonts embedded, cached in ~/.kaizen/kaizen-book/fonts)
node $S/verify.mjs output/book.html      # phone + spread smoke test, screenshots in output/shots/
node $S/pdf.mjs output/book.html         # → book.pdf, book-mono.pdf, book-vol-N.pdf, og.jpg
  • verify.mjs must report all checks passed: no page errors, every chapter opens, nothing clipped past a page, no horizontal scroll, flips cross chapters, and resume keeps the chapter, page, theme and font size. Look at the screenshots yourself, and show the cover and one spread to the author.
  • pdf.mjs prints the book twice so the contents page carries real page numbers, read from the PDF's named destinations with pdfinfo -dests. --only color,mono,volumes,og limits what it makes.
  • Look at the PDF pages before handing them over (pdftoppm -r 40 -png output/book.pdf /tmp/p then a contact sheet): the cover, the contents, a part page, a chapter opening, a page with an image, and the mono cover.

book.json

KeyMeaning
title, subtitle, author, taglineUsed on the cover, title page, contents and link preview
langid, en, or another code. id/en have built-in interface labels; override any with "labels": {…} (keys are in build_book.py)
styleclassic · romance · scifi · fantasy · thriller · literary · children (from assets/styles.json)
themePer-book overrides of the style, e.g. {"cover": {"bg": "#123"}, "accent": "#a33"}
coverPath in book/ to a 2:3 image. Empty means a typeset cover in the style's colours. The mono PDF always uses the typeset cover
copyright, dedicationFront-matter pages in the PDFs (\n for line breaks)
description, urlLink preview text, and the site's absolute URL (needed for og:image)
volumes[{"label": "Volume 1"}, {"label": "Volume 2", "from_part": 6}]. from_part is the 1-based number of the # part a volume starts at
volume_printmono (default) or color: which print the volume PDFs are cut from. An image cover gets the volume label on a band
manuscript, idOther manuscript file name; storage key for reading position (defaults to the title)

To add a style, copy an entry in assets/styles.json (Google Fonts family names; cover pattern is one of frame grid petals slash dots none).

5. Publish

python3 $S/deploy.py book assembles output/deploy/, which can be hosted anywhere static (cd output/deploy && npx vercel --prod, Netlify, GitHub Pages, or a Cloudflare tunnel). Publishing is outward-facing, so confirm with the user before deploying.

  • index.html is a 2 KB page carrying the og tags that then loads reader.html. WhatsApp and other previewers give up on a multi-MB page before they read its head. Don't replace index.html with the book.
  • The reader's "Print / PDF" button opens book.pdf when the site has one, because iOS Safari ignores @page and prints with white margins. Opened as a file, the button prints the built-in print layout instead.
  • The PDFs are snapshots. After any change to the text, rebuild everything in step 4 and redeploy. Volumes are found by part, so they follow the text without hand-kept page numbers.

What the reader does

Cover board with cloth grain that swings open onto a half-title page, contents, and CSS-column pages on textured paper. Phones show one page, and landscape screens 900 px or wider show a spread. Pages turn with a 3D flip (a fade with reduced motion) by swipe, by tapping the outer 30% of the page, or with arrow keys, PageUp/PageDown or Space. Running heads and page numbers on every page (numbered through the whole book; in a spread each chapter starts on a left page), drop cap at each chapter opening, part opener pages, text before the first heading shown as a lead-in before the first chapter, fenced code blocks, footnote markers that open the note, and themes (paper / sepia / night). Font size 13–28 px, and the position is saved per book in localStorage. Text is justified only when a column is at least 380 px wide, to avoid rivers on phones. Paragraphs use dir="auto", so Arabic or Hebrew passages in a left-to-right book display correctly. A fully right-to-left book is not supported yet.

Kaizen

Inside a kaizen run, the brief and outline approvals are the plan approval, each batch of chapters is a build, and the review reads the chapters against brief.md, style.md and the outline. For a built book, the review also needs verify.mjs passing and the PDF contact sheets. Screenshots go in the run's attachments/ for the Preview gate.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.