read-book

/read-book — Extract structured notes from books and long PDFs

Sibling to watch-video. Same content-consumption pattern: ingest → chunk → extract → optionally capture to second-brain.

Step 1 — Parse input

Accept:

• PDF: file path (Claude reads PDFs natively in chunks via Read pages:"X-Y")
• EPUB / MOBI: file path (needs pandoc or ebook-convert to extract — see references/sources.md)
• Markdown / .txt: file path (read directly)
• Pasted text: just use what was pasted
• URL to public-domain text: fetch it with your agent's URL-fetch tool or curl (Project Gutenberg, archive.org, etc.)

Detect type from file extension. If ambiguous, ask.

Step 2 — Parse mode

Invocation	Mode	What you get
/read-book <input>	notes (default)	Chapter-by-chapter: TL;DR + key concepts + quotes + action items + frameworks
/read-book <input> summary	summary	Whole-book TL;DR (1 paragraph) + 3–5 key takeaways + who-it's-for
/read-book <input> quotes	quotes	Pull-quote highlights only, with chapter context and page refs
/read-book <input> study	study	Notes mode + 10–20 spaced-repetition Q&A cards

If the book is long (>200 pages) and mode is unspecified, default to notes but warn it'll take many tool calls.

Step 3 — Get the text + chunk

See references/sources.md for per-source ingestion. Output of this step: text content + a chunking plan.

Chunking strategy (hybrid, in priority order):

1. By chapter if a TOC exists (PDF with bookmarks, EPUB/MOBI converted via pandoc preserves chapter headers)

   • Use pdfinfo <pdf> | grep "Pages" for PDFs
   • Use pdftotext -layout <pdf> | grep -i "^chapter\|^part" for chapter detection, or read TOC from page 1–5
   • EPUB: after pandoc <epub> -o tmp.md, chunks are between # Chapter X headers

2. By page count for PDFs without TOC: 50 pages per chunk

3. By character count for text/markdown: 30,000 chars per chunk (~7,500 words)

Save the chunking plan as ~/Documents/books/<author>-<title-slug>-<YYYY-MM-DD>/chunks.json:

{
  "source": "<path>",
  "title": "<book title>",
  "author": "<author>",
  "type": "pdf",
  "total_pages": 287,
  "chunking": "by-chapter",
  "chunks": [
    {"i": 0, "label": "Introduction", "pages": "1-12"},
    {"i": 1, "label": "Chapter 1: The Problem", "pages": "13-32"},
    ...
  ]
}

Step 4 — Read each chunk

Loop:

1. Read chunk N (Read tool with pages: for PDF, full file for text/MD)
2. Extract per the chosen mode (see references/output-modes.md for templates)
3. Append the chunk's notes to ~/Documents/books/<workdir>/notes-<NNN>-<label-slug>.md

For PDFs, don't read the whole book in one call — Claude's PDF tool maxes around 10 pages. Process chunks individually.

If a chunk fails to extract anything useful (e.g., it's mostly diagrams or front-matter), log the skip and continue.

Step 5 — Aggregate into final notes file

Combine all chunk notes into a single ~/Documents/books/<workdir>/notes.md matching the mode's full-book template (see references/output-modes.md).

Top of the file always has the metadata block + the second-brain-compatible frontmatter:

source: <file path or URL>
captured: YYYY-MM-DD
type: book
book_title: <title>
author: <author>
mode: notes
chunks: <count>
chunking: <strategy>

# <title> by <author>

## TL;DR
<2–3 sentences>

## Key takeaways
1. ...

## Chapter notes
...

## Cross-references (suggested for wiki)
- Could connect to [[Longevity Biomarkers]] (per Chapter 3 discussion of biomarkers)
- Could connect to [[Productivity & Systems]] (per Chapter 7 framework)

The cross-reference suggestions are advisory — they're suggestions for /sb compile to act on, not auto-applied. Keep responsibilities separated.

Step 6 — Offer to capture to second-brain

Ask:

"Want to capture this to second-brain? I'll write it to ${SECOND_BRAIN_VAULT:-$HOME/Documents/SecondBrain}/raw/highlights-<slug>.md matching your vault's highlights- type prefix."

Default is ask, never auto-write. If yes:

1. Copy the final notes.md (with the second-brain-compatible frontmatter at top) to ${SECOND_BRAIN_VAULT:-$HOME/Documents/SecondBrain}/raw/highlights-<slug>.md
2. Tell the user the path
3. Suggest: "Run /sb compile later to merge this into wiki pages — the cross-reference suggestions in the footer are starting points."

If the user skips capture, the workdir still has everything — they can grab the file later.

Step 7 — Report

In chat:

• One-line headline: <title> · <author> · <total_pages or word count> · <mode> · <chunks processed>
• Workdir path
• The TL;DR section
• For notes / study modes: brief list of top 3 takeaways
• For quotes mode: top 3 quotes
• If captured to second-brain: that path too

Modes (quick invocations)

Invocation	Mode	Behavior
/read-book <input>	notes	Full pipeline, default mode
/read-book <input> summary	summary	Just TL;DR + key takeaways (1 read pass for short books, sampled chapters for long)
/read-book <input> quotes	quotes	Chapter-by-chapter, but only output quotes
/read-book <input> study	study	Notes + Q&A spaced-rep cards
/read-book <input> --capture	(any)	Skip the ask step, auto-write to second-brain raw/
/read-book <input> --render pdf	(any)	Also render the final notes.md to PDF via pandoc (uses ~/.local/share/makerskills/render.css). See references/output-modes.md.
/read-book <input> --render html	(any)	Same as above but HTML

Composes with

• second-brain — primary integration: writes highlights-<slug>.md to raw/. Then /sb compile merges into wiki pages.
• deep-research — when a research question turns up a book, /read-book is the next step. Notes feed back into the research brief.
• business-brainstorm — when scoring an idea (e.g., business books on similar models), read-book provides the structured evidence.
• decide — when a decision hinges on what an authority has written (e.g., "should I take VC money?" → read Naval / Jason Cohen), read-book extracts the relevant chapter.
• slide-deck — book takeaways → talk material (book talk pattern).
• watch-video — sibling skill, same content-consumption pattern. Audiobook? Use watch-video transcript mode.
• nonfictionskills / fictionskills — when researching to write a book, this skill reads the comp titles.

Error handling

Failure	Response
EPUB/MOBI without pandoc / ebook-convert	Tell the user: brew install pandoc or brew install calibre (calibre includes ebook-convert)
PDF is scanned (no text layer)	Suggest OCR first: brew install ocrmypdf && ocrmypdf <pdf> <pdf-ocr.pdf>
PDF has no detectable TOC	Fall back to 50-page chunks. Note in the metadata.
Book is unusually long (>500 pages)	Warn cost / time, ask if the user wants summary mode instead of full notes
Chunk extraction empty	Skip the chunk, log, continue. Don't fail the whole run.

Notes on quality

• Don't summarize beyond recognition. A 30-page chapter should produce 8–15 lines of notes, not 3. Compression is good; flattening is bad.
• Preserve specifics. Names, numbers, dates, quotes — keep them. The whole point is later-the user can grep "what did Andy Wilkinson say about X" and find it.
• Quotes are sacred. When you flag a quote, copy it verbatim. Note the page if possible.
• Action items are explicit. If the book makes you think "I should do X," flag it explicitly. These are the highest-leverage outputs.
• Frameworks deserve their own bullets. When the author names a framework (e.g., "the 9-dimension filter," "Save the Cat beats"), call it out by name in the notes.