deep-reader

Files (15)

• README.md
• README.vi.md
• README.zh.md
• SKILL.md
• genre-strategies.md · references/
• note-templates.md · references/
• paper-mode.md · references/
• build-diagram.sh · scripts/
• extract-structure.sh · scripts/
• prepare-text.sh · scripts/
• read-pages.sh · scripts/
• search-book.sh · scripts/
• self-test.sh · scripts/
• split-chapters.sh · scripts/
• verify-quotes.sh · scripts/

SKILL.md (first lines)

# Deep Reader

Read long books and papers the way a careful human researcher does: skim for
structure first, read deeply chapter by chapter with notes as you go, then
synthesize from the notes — never the raw text — at the end. The method comes
from Adler's *How to Read a Book*, SQ3R's Recite step, and Keshav's three-pass
method for papers.

## Why multi-pass, why notes

An LLM's attention dilutes over long contexts, and it loses track of material
buried in the middle of a big prompt ("lost in the middle"). Loading a
500-page book into one context and asking questions about it produces answers
that quietly forget chapter 3 by the time you're discussing chapter 12.

The fix is the same one human researchers use: never hold the whole book in
working memory at once. Read it in passes — first for structure, then chapter
by chapter for content — and externalize what you learn into note files as you
go. The notes become the durable memory; the book itself only needs to be
back in view when you're actively reading a specific chapter or verifying a
specific claim. Page numbers are the coordinate system that makes every claim
traceable back to the source, in this session or a later one.

## Two modes

- **overview** — Adler's inspectional pass only: a book map plus a
  goal-directed summary of the chapters that matter most to the reader's
  purpose. Fast, no per-chapter notes.
- **study** — the full pipeline: reading purpose → inspectional map →
  chapter-by-chapter analytical notes with Recite verification → hierarchical
  synthesis answering Adler's four questions → mechanical quote verification.

The user picks (or you propose one from `mode_hint` + their stated purpose —
see Step 1).

## Workspace layout

Everything the pipeline produces lives in a workspace directory, by default a
sibling of the source file, so it survives across sessions:

```
<slug>-notes/
├── source.txt          # full text with [[page N]] markers — the coordinate system
├── chapters.tsv        # confirmed structure: chNN<TAB>from<TAB>to<TAB>title
├── chapters/           # per-chapter files cut by split-chapters.sh
│   └── ch01-<slug>.txt
├── map.md              # inspectional pass output
├── terms.md            # key-terms ledger, cross-chapter
├── notes/
│   └── ch01-<slug>.md  # one analytical note per chapter (papers: sec01-<slug>.md)
└── synthesis.md        # final synthesis + verification log
```

This workspace, not the SKILL.md scripts, is what makes a later session able
to answer a follow-up question without re-reading the book (see "Answering
from existing notes" below).

## Scripts at a glance

All seven scripts live in `scripts/` under this skill. Run them either as
`bash ./scripts/<name>.sh ...` from the skill directory, or as
`bash /mnt/skills/user/deep-reader/scripts/<name>.sh ...` on claude.ai — both
forms invoke the same script, use whichever matches where you're running.

| Script | Arguments | Purpose |
| --- | --- | --- |
| `prepare-text.sh` | `<input-file> [workspace-dir]` | Convert source to paged `source.txt`, create the workspace |
| `extract-structure.sh` | `<source.txt>` | Heuristic outline seed (a starting guess, not ground truth) |
| `read-pages.sh` | `<source.txt> <from> [to]` | Print a page or page range, with `[[page N]]` markers intact |
| `search-book.sh` | `<source.txt> <pattern> [context-lines]` | Grep the whole book, page-annotated results |
| `split-chapters.sh` | `<source.txt> <chapters.tsv>` | Cut confirmed chapters into standalone files |
| `build-diagram.sh` | `<workspace-dir> [--append]` | Mechanical Mermaid mindmap of the structure |
| `verify-quotes.sh` | `<workspace-dir>` | Catch fabricated quotes and wrong page citations |

## Step 0 — Prepare

Locate the source file, then convert and page it:

```bash
bash ./scripts/prepare-text.sh path/to/book.pdf
# or on claude.ai:
bash /mnt/skills/user/deep-reader/scripts/prepare-text.sh path/to/book.pdf
```

This is idempotent — re-running it on a workspace that already has
`source.txt` reports existing stats instead of reconverting, so it's safe to
call at the start of every session on the same book.

Read the JSON it prints. `pages` and `est_tokens` tell you the book's size;
`mode_hint` gives a starting recommendation (small/medium/large); if
`synthetic_pages` is true (EPUB/DOCX/TXT/MD sources have no real page numbers)
remember that page citations in notes still point into `source.txt`'s own
paging — verifiable, just not the printed page numbers a reader with the
physical book would see.

Two branches before you go further:

- **A workspace with notes already exists** for this book (check
  `<slug>-notes/notes/` for files) — skip straight to "Answering from
  existing notes" below instead of restarting the pipeline.
- **Exit code 2** (missing `pdftotext`/`pandoc`) — fall back to reading the
  PDF/EPUB directly with the Read tool in page batches. You lose
  `verify-quotes.sh`'s mechanical check in this fallback; compensate with
  more frequent manual re-reads of anything you quote.
- **Scripts misbehaving?** Run `bash ./scripts/self-test.sh` — it distinguishes
  an environment problem (missing/broken dependencies) from a usage problem.

## Step 1 — Reading purpose

If the user hasn't said why they're reading this book, ask one question:
"What do you want out of this book?" Purpose isn't a formality — it decides
which chapters get a deep pass and which get skimmed, and it's the yardstick
Step 4's synthesis is judged against.

Once you know the purpose, propose a mode using `mode_hint` plus that purpose
(e.g. a 40k-token book read for one narrow question can stay in overview even
though it would technically fit; a 200k-token book read to write a literature
review needs study mode regardless of size). Let the user confirm or override.

From tronghieu/agent-skills, MIT.

More from tronghieu/agent-skills