SuperAPI AI Directory
Partner中文AI newsFavorites
Skillscrisp-reading

crisp-reading

Data & analytics

View repository

Updated 10-15 23:44

About this skill

CRISP Reading

Your AI deep reading partner. Break down, understand, critique, and internalize a book, producing an interactive HTML reading report.

Architecture: Claude only thinks, scripts handle formatting

路徑 A：PDF/EPUB → extract-text.py → 純文字 ─┐
路徑 B：僅書名 → Gutendex API → TXT 下載 ───┤→ Claude 分析 → JSON → render-report.py → HTML
路徑 C：僅書名（書庫無結果）→ 依公開資料 ──┘
  • Claude is responsible for: reading comprehension, critical analysis, structured thinking → outputs analysis JSON
  • Scripts are responsible for: text extraction (extract-text.py), HTML template filling (render-report.py); templates are handled by scripts and are not loaded into context
  • JSON is an internal intermediate format: after Claude produces the JSON, it is passed directly to render-report.py; the user does not need to and will not receive a JSON file

Workflow

Decision matrix: determine the path based on the input

Input Which steps to take Output
Has PDF/EPUB All of steps one through five HTML report
Has PDF/EPUB + user already has notes Read the notes first, then go through steps one through five HTML report
Book title only Try to obtain the book from a public library → if the full text is obtained, go through steps one through five; otherwise steps four through five (based on public information) HTML report

All paths go through the complete workflow and produce an HTML report.

Step one: Environment preparation

Confirm that pymupdf4llm is available (the only required dependency of extract-text.py):

pip install pymupdf4llm  # 若尚未安裝

Step two: Assess the book size

When the user provides a PDF, first run:

python scripts/extract-text.py book.pdf --info

Example output:

{
  "title": "The Almanack of Naval Ravikant",
  "page_count": 242,
  "estimated_tokens": 95000,
  "needs_chunking": true,
  "suggested_chunks": 2
}

Step three: Text extraction (strategy determined by size)

Small books(estimated_tokens < 80,000): extract the entire book at once

python scripts/extract-text.py book.pdf -o book.md

Large books(estimated_tokens ≥ 80,000): process in batches

# 1. 先提取目錄
python scripts/extract-text.py book.pdf --toc

# 2. 根據目錄結構，按章節分批提取
python scripts/extract-text.py book.pdf --pages 1-50 -o part1.md
python scripts/extract-text.py book.pdf --pages 51-120 -o part2.md
# ...或自動分塊：
python scripts/extract-text.py book.pdf --chunk-size 50 --output-dir ./chunks

Analysis strategy for large books：

  1. First read the table of contents + preface + conclusion (to grasp the whole picture), and complete the TIPS scoring
  2. Read chapters in batches, producing local analysis notes for each batch (arguments, concepts, quotations, critiques)
  3. After reading all chapters, integrate all local notes, merge duplicate concepts, unify the levels of arguments, and supplement cross-chapter critical perspectives
  4. Produce one complete JSON (not multiple concatenated pieces, but a single integrated structure)

Fallback when scripts fail: inform the user of the reason and suggest alternatives (provide an unlocked PDF, install pymupdf4llm, or switch to title mode). EPUB files require gateway.py from the document-to-markdown skill; if unavailable, ask the user to convert to PDF or switch to title mode.

Title mode: try to obtain the full text from a public library (optional)

When only a book title is entered, try to search for the full text from public domain libraries. This step is optional; obtaining the full text improves analysis quality.

Search strategy（Gutendex API）：

  • Chinese book title: add the languages=zh parameter → https://gutendex.com/books?languages=zh&search={中文書名}
  • English book title: search directly → https://gutendex.com/books?search={英文書名}
  • It is strictly forbidden to translate the book title yourself before searching(for example, translating "老殘遊記" into "lao can travels"); search directly with the original book title
  • Alternative: Standard Ebooks https://standardebooks.org/ebooks?query={書名}(English books only)

Process：

  1. Use WebFetch to search the Gutendex API (for Chinese books, remember to add languages=zh）
  2. If a matching result is found, download the TXT format (prefer text/plain; charset=utf-8）
  3. Use extract-text.py to extract the text (or read the TXT directly)
  4. Enter the standard analysis process (steps two to five)
  5. HTML report annotation: "Book source: Project Gutenberg (public domain version)"

Limitations and fallbacks：

  • Public book repositories only include public domain books (mostly published before 1928)
  • No search results → fall back to "based on public information" mode, do not block the process
  • WebFetch unavailable → skip directly, follow the "title only" standard path
  • Not mandatory: if the user explicitly says "no download needed" or "just use your knowledge", skip this step

For the detailed book repository list and API usage, see references/ebook-library.md。

Step 4: Claude analysis → output JSON

Claude reads the extracted text, executes the analysis process (see below), and finally produces an analysis JSON file. For the JSON structure definition, see references/json-schema.md。

Step 5: Render the HTML report

python scripts/render-report.py analysis.json -o reading-report-{slug}.html

The script reads the JSON, applies the HTML template, and outputs the complete report. Zero token consumption.

Analysis process (internal)

The user does not need to know the stage names. Execute in the following order:

  1. Evaluation: Quick TIPS four-dimension scoring (see the quick reference table below), displayed in the report as evaluation metrics
  2. Structural analysis: Extract the book's overall skeleton, core questions, main arguments, and argumentation structure
  3. In-depth analysis: Adler's four questions + Fan Deng's four questions, underlying assumption extraction, Self-Explanation, mental model extraction, and cognitive gap capture
  4. Critical evaluation: Adler's three types of objections, Steel-Manning, six dimensions of quality evaluation
  5. External verification(optional): use WebSearch to search public discussions only when the user explicitly requests it
  6. Internalization and action: Zettelkasten three-layer note structure, action commitment (three elements)
  7. Produce JSON: Structure the analysis results into JSON and hand them to render-report.py for rendering

For the detailed methodology of each stage, see references/analysis.md; for the HTML design specifications, see references/design-spec.md。

TIPS four-dimension scoring quick reference

Each dimension is scored 1-3. The TIPS score serves as a book evaluation metric, displayed in the HTML report, and does not affect analysis depth—all books undergo the full in-depth analysis.

Dimension Code Definition
Toolability T Whether the methods in the book can be used directly
Inspirability I Whether reading it changes the way you think
Practicality P Whether it helps the reader's current situation
Scientificity S Whether the evidence can withstand scrutiny

Scoring quick reference：

  • 1 point: T no actionable methods / I mostly known common sense / P low relevance to the reader / S relies on personal experience or anecdotes
  • 2 points: T has methods but requires your own transformation / I has novel viewpoints / P partially applicable / S has some evidence but not systematic
  • 3 points: T Provides ready-made tool processes / I Fundamentally challenges cognition / P Directly solves the current problem / S Sufficient evidence and rigorous logic

Overall Score Interpretation：

Overall Score Meaning
4-5 Average
6-8 Good book
9-12 Very much worth reading in depth

Core Invariants

  1. Honest about sources — Confirm that you truly have a grasp of the book's content before starting the analysis. When relying only on the book title, clearly mark uncertain parts as "judged based on public information," and never fabricate details
  2. Methodology not exposed — Users will never see Phase numbers, JSON structures, or methodology names (such as Adler, Zettelkasten). TIPS scores will be displayed in the HTML report
  3. Criticism is never absent — The weaker the evidence, the deeper the criticism, but always expressed in natural language
  4. Actions must be specific — Time + target + specific action, none may be missing
  5. Leave space for thought — Actively leave open-ended questions in the report to guide readers toward forming their own judgments, rather than giving a definitive conclusion

Special Case Handling

  • Partial reading: Analyze the parts already read, mark unread parts as pending, and do not speculate
  • Multilingual books: Always output in Traditional Chinese; when quoting the original text, include a Chinese translation. The target readers are Traditional Chinese users. Book title handling rules:
    • English book has a Chinese translated title → Chinese title (original title), e.g., "The Great Gatsby (The Great Gatsby)"
    • English book has no Chinese translated title → use the original title directly
    • Chinese book → use the Chinese title directly
    • The same applies to further reading lists: "Poor Charlie's Almanack (Poor Charlie's Almanack) — Charlie Munger"
  • Author naming rules: For English or original-language authors who have a recognized Chinese translated name, present it in the format "Chinese translated name (original name)," for example "F. Scott Fitzgerald (F. Scott Fitzgerald)"; if there is no recognized Chinese translated name, use the original directly
  • Translation verification rules (mandatory): Traditional Chinese translated titles for book titles and authorsmustbe verified through WebSearch, and may only be used after confirming that they are standard translations recognized by the Taiwanese publishing industry or generally accepted.It is strictly forbidden to guess from memory or transliterate. Verification steps:
    1. Use WebSearch to search for "{original title} Traditional Chinese translated title" or "{original title} Chinese edition"
    2. Confirm that the search results contain clear publication or reliable source support for that translated title
    3. If WebSearch is unavailable or the standard translated title still cannot be confirmed after searching,use the original book title/author name directly, without any translation
    4. The same applies to other books in further reading: when the translated title cannot be confirmed, keep the original
  • User already has notes: Read them first, then supplement and deepen based on them, rather than analyzing from scratch
  • Rendering failure: Check whether the JSON structure conforms to json-schema.md, then rerun render-report.py after fixing it

Script Tools

Script Purpose Dependency
scripts/extract-text.py PDF/EPUB text extraction, table of contents extraction, book information, automatic chunking pymupdf4llm (required); automatically detects the document-to-markdown skill's gateway.py, and prioritizes it if installed (supports more formats such as EPUB)
scripts/render-report.py JSON → HTML report rendering Python standard library only

Reference File Loading Table

Requirement Load File
Analyze JSON structure (must be read for every analysis) references/json-schema.md
Analysis methodology (structural parsing, critique, internalization, action) references/analysis.md
HTML report design specification (only needed when modifying templates) references/design-spec.md
Public e-book sources (when searching the library in title mode) references/ebook-library.md

Loading principles:

  • json-schema.md is loaded before producing JSON (no need to read render-report.py)
  • analysis.md is loaded when entering the analysis phase
  • design-spec.md usually does not need to be loaded (render-report.py applies the template directly); it is only loaded when there is a need to understand or modify the HTML structure