Telestudy

Telestudy — telescopic study guides from anything

A Telestudy guide lets a reader skim a source's key ideas in ~2 minutes, telescope into any idea (one-liner → summary → deep dive), browse the ideas graph (what builds on what), and jump from any idea into the actual chapter/section of the source. One shared CSS/JS template renders everything from a single JSON block per guide, so all guides look and behave identically.

This skill folder is the toolkit:

• assets/guide.css, assets/guide.js — the renderer (copy, never regenerate or inline)
• reference/SPEC.md — the authoring spec: JSON schema, quality bar, graph rules (read it before writing)
• reference/exemplar.html — a complete finished guide (The Psychology of Money)
• scripts/extract_structure.py — TOC/outline extraction from epub (file or unpacked dir) and PDF
• scripts/validate.py — structural validation (run before declaring done)
• scripts/build_index.py — regenerates the library index page

Workflow

1. Ingest the source

Identify what you're distilling and pull its real structure — never invent chapter titles.

• epub: python3 scripts/extract_structure.py (handles zip epubs and unpacked dirs).

Read actual chapter text via zipfile/unzip -p, or the xhtml files directly.

• PDF: same script (uses pypdf; pip install pypdf into a venv if missing). Extract page text

with pypdf when you need to ground content.

• Article / web page: fetch it; sections (headings) play the chapter role.
• Apple Books library item: look up the asset id and file path:

sqlite3 ~/Library/Containers/com.apple.iBooksX/Data/Documents/BKLibrary/BKLibrary-*.sqlite "SELECT ZASSETID, ZTITLE, ZPATH FROM ZBKLIBRARYASSET WHERE ZTITLE LIKE '%%';" (copy the db to a scratch dir first if it's locked). assetId gives the guide an ibooks://assetid/ deep link.

If you know the work deeply, write from knowledge and use the extracted TOC for the chapter map. If not, skim the actual text first — accuracy beats speed; grounding is non-negotiable.

2. Choose the destination

• Adding to an existing library (a folder with assets/guide.css + books/): write the guide

to books/.html with asset hrefs ../assets/…, then rerun scripts/build_index.py . If the user has a Reading Room library already, prefer it.

• Standalone guide: create -guide/ next to the source (or where asked) containing

assets/ (copied from this skill), and .html at the top with asset hrefs assets/… and "library": false in the JSON.

Always COPY assets/guide.css + assets/guide.js from this skill folder — do not re-author them. If the destination library's assets differ from the skill's, the skill's are newer; sync them.

3. Author the guide

Read reference/SPEC.md in full, study reference/exemplar.html, then write the single HTML file: shell + one ` block. Scale idea count to the source (book 9–15, paper 5–8, article 4–6). Give the dependsOn` graph real care — edges mean "you must grasp X to fully get Y", and the set must be a connected acyclic DAG.

For the source link, set assetId (Apple Books) or sourceUrl (article URL, or file:///… for a local PDF) and optionally sourceLabel.

4. Validate and verify

• python3 scripts/validate.py — fix every failure (including disconnected graph

nodes: wire them with semantically honest edges).

• Open the result in a browser when feasible and confirm the cards telescope and the graph renders.

5. Batch mode

For many sources at once, fan out one subagent per source: each agent gets this skill folder's SPEC + exemplar paths, its source's path/TOC/assetId, and the output path — then validate all results centrally and rebuild the index once at the end.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: eranshir
• Source: eranshir/Telestudy
• License: MIT

Install and usage instructions live in the source repository linked above.