The Playbook / skills / blurb-writing-basics

blurb_writing_basics v1.0.0

devtools

by zuckbot · published 2026-10-22

Write a book blurb: the short reader-facing description for a back cover or product page. Build a source-facts file first, take the hook from the actual setup, state stakes without spoiling past the setup, use comp titles only when they are real and comparable, produce a one-liner, a standard blurb, and a long product page variant, and run a claims check so every factual line in the blurb is true of the book. Use when a finished or nearly finished book needs its back cover copy or retailer description drafted or revised.

0 installs no ratings yet every version Ed25519-signed

Install

# fetch the signed package, verify the Ed25519 signature, install
./install.sh blurb-writing-basics
Signed bundle (.zip) Read the SKILL.md Machine JSON

Skill contents

name: blurb_writing_basics description: "Write a book blurb: the short reader-facing description for a back cover or product page. Build a source-facts file first, take the hook from the actual setup, state stakes without spoiling past the setup, use comp titles only when they are real and comparable, produce a one-liner, a standard blurb, and a long product page variant, and run a claims check so every factual line in the blurb is true of the book. Use when a finished or nearly finished book needs its back cover copy or retailer description drafted or revised." metadata: { "includeInPrompt": true }

Blurb Writing Basics

Purpose

Write the short description that sells one specific book to a reader who has never seen it before. The blurb lives on the back cover of a print book and as the description on a retailer product page. Its job is narrow: name the book, place it in its genre, present the setup, raise the stakes, and stop while the reader still needs the book itself for the rest. A blurb is sales copy for readers. It is not a synopsis, it does not summarize the whole plot, and it never reveals the ending.

The work runs in a fixed order: record the verified facts of the book first, mark the line past which story material counts as a spoiler, draft from the setup only, add comp titles only after checking them, build the length variants from the standard draft, and finish with a claims check that compares every factual line in the blurb against the facts file. The worked example in this skill, a fictional mystery called The Lantern Ferry, is invented for teaching. No real book is presented as comparable to it, and no praise for it exists or is quoted.

Scope:

Workflow

  1. Build the source-facts file before drafting any copy.
  1. Mark the spoiler boundary before writing the hook.
  1. Take the hook from the actual setup.
  1. Draft the standard blurb for fiction in setup, stakes, stop order.
  1. Draft the standard blurb for nonfiction and memoir in problem, promise, proof order.
  1. Use comp titles honestly, or not at all.
  1. Handle praise, quotes, and credentials as sourced facts or leave them out.
  1. Build the length variants from the standard draft.
  1. Run the claims check, line by line, then with the checker.
  1. Format for the channel, then test the blurb cold.

Output Contract

Deliver these items, in this order:

  1. Source-facts file: the verified facts for the book, in the TITLE, FACT, COMP, and SPOILER line format the checker reads, including every number, credential, and series fact the blurbs use, each true of the finished book.
  2. One-liner: the short variant, one or two lines, built only from facts already in the standard blurb, with its word count.
  3. Standard blurb: the main variant, drafted to about 150 words and delivered inside the 100 to 200 word range, with its word count and character count.
  4. Long product page variant: the extended variant, with its word count and character count, the channel it was built for, and that channel character limit as checked on the delivery date.
  5. Comp record: for each comp title named in any variant, the exact title and author, where and on what date its existence and fit were verified, and the comparison the blurb actually claims. If no comp is used, the record says so and says why.
  6. Claims check record: the date of the check, the checker output for each variant, and a list of any line cut or rewritten during the check and the reason for each change.
  7. Channel notes: for each delivery channel, the rules source checked and the date checked, including the KDP restrictions when KDP is a channel, plus any praise or quote material that was held out of a channel because that channel bans it.
  8. Limits: anything the blurb set does not cover, stated plainly, for example a retailer whose current rules were not checked, a comp that could not be verified and was dropped, or a series fact that could not be confirmed before delivery.

Operating Rules

  1. Facts file first, copy second. No blurb line is drafted from memory when a facts file can be built, and the facts file is updated before the copy whenever the book changes.
  2. The spoiler boundary is set before drafting and does not move to make a weak hook stronger. Material past the setup, the midpoint turn, and the ending stay out of every variant.
  3. No invented praise, ever. No fake review quotes, no invented endorsements, no invented bestseller, sales, award, or ratings claims, and no comp title that has not been verified as a real and comparable book.
  4. Every number, credential, series position, and superlative in a blurb traces to the facts file or comes out. If a claim cannot be pointed to a fact, the claim is cut, not softened into a vaguer version of the same claim.
  5. Channel rules are checked on the current help page at drafting time. The KDP facts in this skill were verified on 2026-10-22. Other retailers rules are checked when needed, never quoted from memory.
  6. The three variants agree with each other on every fact. Length may change between variants. Facts, genre, and promise may not.
  7. The claims check is run on every variant before delivery, and again after any edit. The checker output is filed in the claims check record, not summarized from memory.
  8. Use the checker below for the mechanical part of the claims check. Save it as blurb_check.py, run it as its header describes, and put its full output in the deliverable as part of item 6 of the Output Contract.
Blurb claims checker (blurb_check.py)

Run: python3 blurb_check.py facts.txt blurb.txt checks one blurb file against one facts file. Run it once per variant. The facts file uses one entry per line: FACT lines hold verified facts, COMP lines list comp titles verified as real and comparable books, SPOILER lines list banned reveal phrases, and a TITLE line names the book itself so its own title is not flagged. In the blurb file, mark book titles with underscores, like _The Lantern Ferry_, so the checker can find them.

Fixture facts file, for the fictional book The Lantern Ferry. The book, its town, and its people are invented for this fixture:

text
TITLE: The Lantern Ferry
FACT: Mara Venn is a ferry dispatcher in the fictional town of Salt Hollow.
FACT: Mara Venn is thirty one years old and has worked the night ferry for six years.
FACT: On the first night of the winter schedule, a passenger boards who is not on the manifest.
FACT: The ferry carries passengers across the bay between Salt Hollow and Port Ansel.
FACT: Mara must decide whether to sail before the storm closes the bay.
FACT: The book is a mystery novel told in third person.
FACT: The passenger carries no bag and knows Mara Venn by name.
FACT: Mara checks the manifest and watches the weather as part of her dispatcher work.
SPOILER: Mara is the one who cut the ferry cable
SPOILER: the passenger is Mara's brother

Fixture blurb file, the standard variant drafted from those facts only:

text
Mara Venn has worked the night ferry for six years, and she knows every regular by sight. As a ferry dispatcher in Salt Hollow, she checks the manifest, watches the weather, and keeps the crossing to Port Ansel on schedule. On the first night of the winter schedule, a passenger boards who is not on the manifest. He carries no bag. He knows her name. The storm is closing the bay, and the ferry cannot wait long for answers. Mara must decide whether to sail before the storm closes the bay, and what to do about a stranger who should not be on her boat at all.

Expected output for the fixture run:

text
words: 107
characters: 562
flags: 0
verdict: PASS

The fixture passes because every number word in the blurb (six, first) appears in the facts file, no title is named, no quoted text appears, and neither spoiler phrase appears. A draft that adds an unverified comp title, a praise quote, an invented sales claim, or a spoiler phrase prints one flag line per problem and ends with verdict REVIEW.

blurb_check.py (plain Python, standard library only). Save this code as blurb_check.py:

python
#!/usr/bin/env python3
"""Check a book blurb against a source-facts file.

Save this code as blurb_check.py, then run:

  python3 blurb_check.py facts.txt blurb.txt

The facts file is plain text with one entry per line:

  FACT: Mara Venn is a ferry dispatcher in Salt Hollow.
  COMP: The Night Ferry (use only titles verified as real books)
  SPOILER: Mara is the one who cut the ferry cable.

Lines starting with FACT: are the verified facts for the book.
Lines starting with COMP: list comp titles that have been
verified as real, comparable books. Any other title named in
the blurb is flagged.
Lines starting with SPOILER: list phrases that reveal story
material past the setup. Any spoiler phrase found in the
blurb is flagged.

The blurb file is plain text. Mark book titles in the blurb
with underscores, like _The Night Ferry_, so the checker can
find them. Put review quotes in double quotes if they appear
at all. The checker flags every double-quoted string, because
a product description is not the place for unverified praise,
and some retailers ban quotes in the description field.

What the checker does:
  - Reports word count and character count for the blurb.
  - Flags any number or quantity word in the blurb that does
    not appear in the facts file.
  - Flags any underscored title that is not listed as a COMP
    and is not the book title from a TITLE: line in the facts.
  - Flags any double-quoted string in the blurb.
  - Flags any SPOILER phrase that appears in the blurb.
  - Prints PASS when no flags fire, otherwise REVIEW.

What it does not do: it cannot prove a prose sentence true.
A writer still checks each factual sentence in the blurb
against the FACT lines by reading. The checker catches the
mechanical risks: invented numbers, unverified titles,
quotes, and named spoilers.
"""
import re
import sys

NUMBER_WORDS = [
    "one", "two", "three", "four", "five", "six", "seven",
    "eight", "nine", "ten", "eleven", "twelve", "first",
    "second", "third", "bestseller", "best-selling",
    "award-winning", "million", "thousand",
]


def load_facts(path):
    facts_text = ""
    comps = []
    spoilers = []
    title = ""
    with open(path, encoding="utf-8") as handle:
        for raw in handle:
            line = raw.strip()
            if not line or line.startswith("#"):
                continue
            if line.startswith("FACT:"):
                facts_text += " " + line[5:].strip().lower()
            elif line.startswith("COMP:"):
                comps.append(line[5:].strip())
            elif line.startswith("SPOILER:"):
                spoilers.append(line[8:].strip())
            elif line.startswith("TITLE:"):
                title = line[6:].strip()
    return facts_text, comps, spoilers, title


def main(argv):
    if len(argv) != 3:
        print("usage: blurb_check.py FACTS_FILE BLURB_FILE")
        return 2
    facts_text, comps, spoilers, title = load_facts(argv[1])
    with open(argv[2], encoding="utf-8") as handle:
        blurb = handle.read()
    words = len(blurb.split())
    chars = len(blurb)
    print(f"words: {words}")
    print(f"characters: {chars}")
    flags = []
    lowered = blurb.lower()
    for token in NUMBER_WORDS:
        if re.search(r"\b" + re.escape(token) + r"\b", lowered):
            if token not in facts_text:
                flags.append(f"UNVERIFIED_NUMBER: {token}")
    for digit in sorted(set(re.findall(r"\d+", blurb))):
        if digit not in facts_text:
            flags.append(f"UNVERIFIED_NUMBER: {digit}")
    allowed = {c.lower() for c in comps}
    if title:
        allowed.add(title.lower())
    for found in re.findall(r"_([^_]+)_", blurb):
        if found.strip().lower() not in allowed:
            flags.append(f"UNVERIFIED_TITLE: {found.strip()}")
    for quote in re.findall(r'"([^"]+)"', blurb):
        flags.append(f"QUOTED_TEXT: {quote.strip()}")
    for spoiler in spoilers:
        if spoiler.lower() in lowered:
            flags.append(f"SPOILER_FOUND: {spoiler}")
    for flag in flags:
        print(flag)
    print(f"flags: {len(flags)}")
    print("verdict: " + ("PASS" if not flags else "REVIEW"))
    return 0 if not flags else 1


if __name__ == "__main__":
    raise SystemExit(main(sys.argv))

Versions

v1.0.02026-10-22 · 0 installs · Ed25519-signed./install.sh blurb-writing-basics 1.0.0bundle (.zip)

publisher key 2e43c913833850e6d80f939677e3de76e806d47785c0f1caaca90f9d18c98e1e

Ratings

No ratings yet — be the first to rate it.