Index of every page on this site: llms.txt
All skills
coreyhaines31 avatar

/read-book

@4cb94db
Run it yourself

When you want to read and extract structured notes from a book — PDF, EPUB, MOBI, markdown, .txt, pasted text, or URL to a public-domain work. Reads in chunks (by chapter when a TOC exists, by 50-page blocks otherwise), extracts per-chapter TL;DR + key concepts + quotes + action items + frameworks, and offers to capture to second-brain raw/ as a highlights- file. Four modes — notes (default, chapter-by-chapter), summary (whole-book TL;DR + 3–5 takeaways), quotes (pull-quote highlights only), study (notes + Q&A spaced-rep prep). Triggers on "/read-book," "read this book," "extract notes from this PDF," "what's in this book," "summarize this ebook," "pull quotes from this." Sibling to watch-video (same content-consumption pattern, different medium).

Use this Skill: https://skilld.dev/gh/coreyhaines31/makerskills/read-book

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈194 tokens for metadata: the name and description. ≈2k when used: this file. ≈2.5k more on demand in 2 files.

Description uses 9.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈769 characters, or 9.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

/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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert1mo3 checks · Risk HIGH
  • Gen Agent Trust Hub1mo

    This skill provides a robust framework for reading and summarizing books in various formats. However, it presents a high security risk due to the inclusion of instructions for executing commands with root privileges and a significant attack surface for indirect prompt injection via untrusted external files and URLs.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: MEDIUM · 1 issue

Signed by skilld at 4cb94db. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last month
metadata
{
  "version": "0.1.1"
}

README badge

README badge for coreyhaines31/makerskills/read-book