Agent skills for Readwise Reader

version
0.1.0
GitHub stars
329

Install

/plugin install readwise@readwise-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add readwiseio/readwise-skills.

Contents

Discovered from source

Skills 11

Draft a long-form book review from a user's Reader highlights — not just the target book, but pulling in related highlights from their entire library to build original arguments.

The goal is a review that's more interesting than the book itself: summary + critique + original ideas, where the original ideas come from connecting the book to everything else the user has read.

Readwise Access

Check if Readwise MCP tools are available (e.g. mcp__readwise__reader_list_documents). If they are, use them throughout. If not, use the equivalent readwise CLI commands instead (e.g. readwise list, readwise read <id>, readwise highlights <id>, readwise search <query>). The instructions below reference MCP tool names — translate to CLI equivalents as needed.

Setup

  1. Check for persona file. Read reader_persona.md in the current working directory if it exists. Use it to understand the user's interests, reading goals, and voice — this shapes the review's framing, what connections to prioritize, and what the user is likely to care about. If no persona file exists, proceed without it and ask the user about their purpose for reading the book if it's not obvious from their highlights.

  2. Parse the argument as a book title or search term.

/book-review Merchant Kings
/book-review 7 Powers

Phase 1: Pull the Book's Highlights

1.1 Find the book

Search Reader for the target book:

mcp__readwise__reader_search_documents(query="[book title]", category_in=["epub", "pdf"])

If no results, broaden to all categories. If multiple matches, list them and ask the user to pick.

1.2 Get highlights

mcp__readwise__reader_get_document_highlights(document_id="[book_id]")

Read every highlight. Count them. If fewer than 10, warn the user — may not be enough material for a substantive review. Ask whether to proceed or wait.

1.3 Get the full document details

mcp__readwise__reader_get_document_details(document_id="[book_id]")

Pull title, author, summary, cover image. You'll need these for the final output.


Phase 2: Extract Claims

Process every highlight into an atomic claim. This is the step that turns "I highlighted this paragraph" into structured, searchable research material.

For each highlight:

  1. Read the highlighted text and any user note/annotation
  2. Write a single present-tense declarative claim (under 10 words when possible)
  3. If the user left a note, weight the claim toward what the note focused on

Claim quality standards:

Good claims are specific, searchable facts or assertions:

  • "chimney sweeps died of scrotal cancer from coal soot"
  • "Ottoman harem trained slave girls as elite bureaucrats"
  • "monsoon winds enabled global maritime trade"

Bad claims are vague or generic:

  • "coal mining had health consequences"
  • "the author discusses Ottoman succession"
  • "interesting point about slavery"

After processing all highlights, review the full list. Reject and rewrite any that are:

  • Generic/boring ("author discusses X")
  • Duplicative (two claims saying the same thing differently — consolidate)
  • Vague (doesn't stand alone without reading the highlight)

Store the claims as a working list grouped by theme. This becomes your outline.


Phase 3: Search the Library for Related Material

This is what makes the review more than a summary. For each major theme cluster from Phase 2, search the user's full Reader library for related content.

3.1 Theme-based searches

For each theme cluster (aim for 3-6 themes):

mcp__readwise__reader_search_documents(query="[theme keywords]", limit=20)

Pull highlights from the top hits:

mcp__readwise__reader_get_document_highlights(document_id="[related_doc_id]")

You're looking for:

  • Supporting evidence from other sources that strengthens a claim
  • Contradictions that complicate the book's argument
  • Parallel examples from different domains (the user read about X in biology, the book says the same about economics)
  • The user's own prior thinking visible in their notes/annotations on related docs

3.2 Author search

mcp__readwise__reader_search_documents(query="[book author name]")

Check if the user has read other work by the same author. Prior context enriches the review.

3.3 Extract related claims

For each relevant highlight from a related document, extract a claim the same way as Phase 2. Tag it with its source document so you can cite it properly.

Result: You should now have:

  • The book's claims (Phase 2), grouped by theme
  • Related claims from the broader library (Phase 3), mapped to those same themes
  • A sense of where the user's reading supports, complicates, or extends the book

Phase 4: Supplement with Web Research

Fill gaps that the user's library doesn't cover. Keep this focused — the library research is the core, web research is supplemental.

  • Search for academic sources, author interviews, other reviews
  • Look for Substack writers or bloggers covering the same topic

Phase 5: Write the Review

A great book review has three elements (per the ACX Book Review Contest wisdom):

  1. Summary — Show what the book is about and why it's interesting. Without this, readers are confused.
  2. Critique — An actual quality and agreement judgment. Without this, it isn't a review.
  3. Original ideas — Connect the book to broader patterns from the user's reading. Without this, nobody is particularly impressed.

The original ideas come from Phase 3 — the related highlights from the user's library. This is the whole point of the skill.

Structure

[Opening: What the book is and why it matters — a specific fact or scene, not a vague hook.
Leave a %% TODO %% for the user to add how they found the book and why they read it
if context wasn't already in the document note.]

## [Thematic section 1 — informative header, not clever]

[Summarize the book's argument on this theme. Use block quotes from the book's highlights.
Then EXPAND: bring in related material from the user's other reading. This is where the
review becomes more than a summary — it's synthesis.]

> "Block quote from the book" — Author, *Book Title*

[The user also highlighted something in [Related Document] that complicates/supports this:
weave it in naturally. Cite the source with a URL link to the original source, NOT the Reader link.]

## [Thematic section 2]

[Same pattern: book's argument → user's related reading → synthesis.
Each section should advance an argument, not just list facts.]

## [Thematic section 3+]

[Keep going. Organize by theme, not by chapter. Every section should have at least
one connection to something outside the book itself.]

## What the Book Gets Wrong (or Misses)

[Honest critique. Use the user's other reading as evidence where it contradicts
or complicates the book. This is where the related-document research pays off most.]

## Further Reading

- Description with [embedded link](url) for sources worth exploring that were NOT
  linked above but are related to the core themes of this review.

Voice Rules

You are drafting FOR the user, not impersonating them:

  • Don't manufacture emotion — No "I was struck by", "I was fascinated to learn." State facts. The user adds reactions.
  • Don't manufacture personal details — No "this reminded me of my childhood." If the user wrote something in a highlight note, reference it. Otherwise, leave a %% TODO %%.
  • Leave explicit gaps — Use %% TODO: [what the user should add] %% for personal hooks. These signal where the user needs to fill in their own experience.
  • Honest about gaps — "I don't know" beats hedging. If unsure, say so or leave a TODO.
  • First person — You're writing a draft the user will edit, not a report about them.
  • If a persona file exists, use it to inform which connections to prioritize and what framing the user would find natural — but still leave TODOs for personal details you're not sure about.

Length

Err long. 2,000-10,000 words for a substantial book. The ACX contest data shows longer reviews with genuine insight outperform shorter ones. Depth > brevity, as long as every paragraph earns its place. If the user's highlights are sparse (10-20), aim for 1,000-2,000 instead.

Links and Sources

  • Bookshop.org link for the target book on first mention
  • Real URLs only — never leave placeholder links like (url) or (link)
  • When citing a related document from the user's Reader library, link to the original source URL (from document details), not the Reader URL
  • Bias toward web sources that can be read in full without a paywall, like Substack or open access PDFs. Do not source from books someone would need to purchase to read.

Phase 6: Quality Gate

Separate pass. Do not skip. Do not combine with Phase 5.

Re-read the full draft and fix every instance of:

Banned Vocabulary

Never use these. Find concrete alternatives.

BannedUse instead
Additionally"Also" or restructure
Crucial / Pivotal / Key (adj)Be specific about why it matters
Delve / Delve into"examine", "look at", or just start
Enhance / FosteringBe specific about what improved
Landscape (abstract)Name the actual domain
Tapestry (figurative)Name the actual pattern
Underscore / Highlight (verb)State the point directly
Showcase"shows", "demonstrates"
Vibrant / Rich (figurative)Be specific
Testament / EnduringJust state the fact
Groundbreaking / RenownedBe specific about what's notable
Garner"get", "earn", "attract"
Intricate / Intricacies"complex" or describe the actual complexity
Interplay"relationship", "tension", or describe it
Serves as / Stands asUse "is"
Nestled / In the heart ofJust name the location

Banned Structures

PatternFix
"Not just X, it's Y" / "Not A, but B"State Y directly
Rule of three ("innovation, inspiration, and insights")Use the number of items the content needs
"-ing" analysis ("highlighting the importance of...")State the importance directly
"From X to Y" (false ranges)List the actual items
Synonym cycling (protagonist/hero/central figure)Pick one term, reuse it
"Despite challenges, the future looks bright"State the actual situation
"Exciting times lie ahead"End with a specific fact
"X wasn't Y. It was Z." (dramatic reveal)Collapse to single positive statement
"The detail that stopped me in my tracks"Start with the fact
"genuinely revolutionary"Use a specific descriptor
Any melodramatic one-liner meant to sound profoundDelete it
"I'd forgotten I knew"Delete. Never frame knowledge as rediscovered.

Checklist

  • 6a. Grep the draft for every banned word/pattern above. Fix every match.
  • 6b. Check links — every source has a real URL. No placeholders.
  • 6c. Check em dash density — max 2-3 per section. Convert excess to commas, colons, periods.
  • 6d. Check word repetition — any word appearing 3+ times in a paragraph. Vary or reduce.
  • 6e. Read the opening paragraph. Does it sound like a person or like an AI summarizing a book? If the latter, rewrite.
  • 6f. Verify every section connects to material beyond the book itself. If a section is pure summary with no synthesis, add related-library connections or cut it.

Phase 7: Publish to Reader

Create the review as a new document in Reader:

mcp__readwise__reader_create_document(
  url="https://reader-review.internal/[slug]-[ISO-timestamp]",
  title="[book title] — Review Draft",
  author="Ghostreader",
  category="article",
  summary="Review draft based on [N] highlights from [Book Title] and [M] related documents",
  html="[converted HTML of the review]",
  notes="DRAFT for editing. Based on highlights from: [list source document titles]"
)

Return the document URL to the user.


What Makes This Different from a Summary

The whole point of Phase 3 (library search) is that the review should contain ideas the author of the book never had. The user's reading history is a unique lens:

  • They read a book about Roman logistics AND a book about supply chain management → the review connects them in a way neither book does alone
  • They highlighted a contradicting claim in a different source → the review challenges the book with evidence the user already found compelling
  • They left a note on a highlight in an unrelated article that turns out to be relevant → the review surfaces a connection the user may not have consciously made

This is how you get "original ideas" — the third element that separates a competent review from an impressive one. The user's library IS the original thinking.


Error Handling

  • Book not found in Reader: Report search terms tried, ask for correct title or document ID.
  • Fewer than 10 highlights: Warn — may not be enough. Ask whether to proceed.
  • No related documents found: Proceed with book-only review but warn that it'll be more summary-heavy. Lean harder on web research.
  • Reader create fails: The draft text is already generated — output it as markdown so the user can save it manually.
  • Any unexpected failure: Say what failed, what's already done, where partial output is.

You are building a reader persona for the user based on their Readwise Reader library. This persona file is used by other skills (triage, quiz, etc.) to personalize their experience.

Readwise Access

Check if Readwise MCP tools are available (e.g. mcp__readwise__reader_list_documents). If they are, use them throughout (and pass this context to the subagent). If not, use the equivalent readwise CLI commands instead (e.g. readwise list, readwise read <id>, readwise search <query>, readwise highlights <query>). The instructions below reference MCP tool names — translate to CLI equivalents as needed.

Welcome

Open with a brief introduction:

Build Persona · Readwise Reader

I'll analyze your reading history — saves, highlights, and tags — and build a reader_persona.md profile in the current directory. Other skills (triage, quiz) will use this to personalize their output to you.

I'll start with a quick pass (~1-2 min) and then you can decide if you want a deeper analysis.

Process

IMPORTANT: This skill involves fetching a lot of data. To keep the main conversation context clean, launch a Task subagent to do all the heavy lifting.

Phase 1: Quick Pass

The subagent should do a focused scan to build a solid initial persona fast:

  1. Gather data. Run ALL of these in parallel (one batch of tool calls):

    • 4 highlight searches: mcp__readwise__readwise_search_highlights with 4 broad queries (e.g. "ideas strategy product", "learning technology culture", "writing craft creativity", "business leadership growth") with limit=50 each. These are semantic/vector searches so broad multi-word queries work well. Highlights are cheap and high-signal — cast a wide net.
    • 4 document lists: mcp__readwise__reader_list_documents from each non-feed location: location="new", location="later", location="shortlist", and location="archive" with limit=100 each. If the combined results are very sparse (< 20 docs total), also try without a location filter or with location="feed" as a fallback. Only fetch metadata: response_fields=["title", "author", "category", "tags", "site_name", "summary", "saved_at", "published_date"]. Do NOT fetch full content.
    • Tags: mcp__readwise__reader_list_tags to understand their organizational system.
  2. Parse results efficiently. The JSON responses from document lists can be large (25k+ tokens). Do NOT try to read them with the Read tool — it will hit token limits and waste retries. Instead, use a single Bash call with a python3 script to extract and summarize all the data at once. The script should parse all result files together and output:

    • Document counts by category
    • Top 20 sites, authors, and tags
    • Save velocity by month
    • All docs saved in the last 3 weeks (title, category, author, date)
    • A representative sample of highlight texts with their source titles/authors
  3. Write the persona. Write reader_persona.md to the current working directory with these sections:

    • Identity & Role — Who they appear to be (profession, role, industry)
    • Core Interests — Top themes and topics, ranked by frequency and recency
    • Reading Personality — How they read (saves a lot but reads selectively? highlights heavily? prefers short or long-form?)
    • Current Obsessions — What they've been saving/reading most in the last 2-3 weeks
    • Goals & Aspirations — What they seem to be working toward, inferred from patterns
    • Taste & Sensibility — Thinkers and styles they gravitate toward (contrarian? practical? philosophical? technical?)
    • Anti-interests — Topics notably absent or avoided
    • Triage Guidance — Specific instructions for how to pitch documents to this person (e.g. "lead with practical applicability", "connect to their interest in X", "bar is high for AI content — flag when it's genuinely novel")
  4. Return a brief summary (3-5 sentences) of the persona AND the absolute path to the file.

Subagent speed rules:

  • Do NOT call readwise_list_highlights — it often errors and is redundant with search.
  • Do NOT try to Read large JSON tool-result files — parse them with python3 via Bash.
  • Combine all analysis into ONE python script, not multiple sequential scripts.
  • Maximize parallel tool calls. Every API fetch in step 1 should be a single parallel batch.

Phase 2: Deep Pass (optional)

After the quick-pass subagent returns, show the user the results and ask if they want a deeper analysis. If yes, launch a second subagent that:

  • Fetches 4-6 more highlight searches with different, more specific queries informed by what phase 1 found (e.g. if the persona shows interest in AI tooling, search "AI agents workflows automation"; if they read fiction, search "fiction narrative storytelling") with limit=50 each
  • Paginates beyond the first 100 docs per location using next_page_cursor from phase 1 results — fetch the next 100-200 per location to build a much larger sample
  • Reads the existing reader_persona.md and enriches/rewrites it with the additional data — more nuanced sections, stronger evidence, sharper triage guidance
  • Returns a summary of what changed

After Each Subagent Returns

  1. Show the file link. Always tell the user: reader_persona.md was written to {absolute_path}. Display the full path so they can open it.
  2. Show a summary of the persona (use the subagent's returned summary).
  3. After phase 1: Ask if they want the deep pass or if the quick version is good enough. Also ask if they want to adjust anything.
  4. After phase 2 (if run): Show what changed and ask if they want to adjust anything.
  5. If adjustments needed, edit the file directly based on their feedback.
  6. Confirm saved. Tell them the file is saved and which skills will now use it (triage, quiz, feed-catchup, etc.).

You are helping the user catch up on their Readwise Reader RSS feed. Follow this process carefully.

Readwise Access

Check if Readwise MCP tools are available (e.g. mcp__readwise__reader_list_documents). If they are, use them throughout. If not, use the equivalent readwise CLI commands instead (e.g. readwise list, readwise read <id>, readwise move <id> <location>). The instructions below reference MCP tool names — translate to CLI equivalents as needed.

Setup

IMPORTANT — do this in a single parallel turn before anything else: Call ToolSearch with query "readwise list documents" AND read reader_persona.md at the same time. Both must happen in the same message as parallel tool calls. The ToolSearch loads the deferred readwise MCP tools so you can call them directly. Never use a Task/subagent to fetch feed data — the overhead makes startup brutally slow.

  1. Check for persona file. (Done in parallel above.) Use it throughout the session to personalize commentary and picks. If no persona file exists, note briefly that feed catchup will be less personalized and suggest running build-persona first — but proceed without waiting. If you show this message, add · · · after it.

  2. Fetch feed documents. Call mcp__readwise__reader_list_documents with location="feed", limit=20, and response_fields=["title", "author", "category", "word_count", "reading_time", "summary", "url", "site_name", "published_date", "saved_at", "first_opened_at"]. Documents come back most-recently-saved first. Filter to items where first_opened_at is null (unseen). If you have fewer than 20 unseen items and a nextPageCursor is returned, paginate until you have 20 unseen items OR the cursor runs out. Hold all unseen items in memory. (Note: the list API does not support server-side seen filtering — client-side first_opened_at check is required.)

  3. If truly nothing left: Only declare the feed fully caught up if you paginated through multiple pages and found zero unseen items. In that case, say so briefly and end.

  4. Pick the top 5. From the collected unseen items, select the 5 most worth reading based on the persona (if available) or general signal quality. Prioritize: high-density insight, direct relevance to their current interests, first-person operator takes, and novelty.

Opening Format

Render the overview exactly like this:

📡 Reader Feed

{1-2 sentences explaining what you looked at and what stood out — e.g. "Scanned the last 20 unseen items. AI and software architecture dominate, with a few standouts worth pulling."}

Today's picks (spanning {human-readable time range, e.g. "the last 8 hours" or "Feb 24–26"}):

#TitleSourceTimeWhy
1Titlesite_namereading_timeOne-line reason this made the cut
2............

{1-2 sentences of commentary on the picks as a set — what the pattern is, or why these five in particular.}

· · ·

Want to act on any of these, or browse everything?

  • Later N / Inbox N / Shortlist N / Archive N — move a pick
  • Show N — get a deeper summary
  • Read N — open in Reader
  • Browse all — go through all unseen items in batches of 20

Browse Loop

If the user says "browse all" (or similar), enter the batch-by-batch loop. Present unseen items 20 at a time:

The Table

Before the table, add a single line with the time range covered by the batch, e.g. "Feb 26, 3:00–11:00 PM" or "last 4 hours" — derived from the saved_at values of the items in that batch.

#TitleSourceTimeSummary
1Titlesite_namereading_timeBrief summary from metadata — one line, truncated if needed
2............

After the table, give a brief commentary (1-2 sentences) on the batch — what stands out relative to their interests.

Options

  • Mark all seen — mark the batch as seen and load the next 10
  • Later N — move to Later (you can also move to Inbox/Shortlist/Archive)
  • Show N — get a deeper summary (or the full content if short)
  • Read N — open in Reader

(You can act on multiple items at once, e.g. "later 2, 5, 8")

Handling Responses

  • "Mark all seen" / "next" / "seen" — Call mcp__readwise__reader_bulk_edit_document_metadata with documents set to [{document_id: <id>, seen: true}, ...] for every document in the current batch. This is a single call, not one per document. Do not move or archive them. Then display the next batch of 20.
  • "Later N" — Move that document to later location. Confirm briefly, then continue.
  • "Later N, N, N" — Move multiple documents to later. Confirm briefly.
  • "Inbox N" / "Shortlist N" / "Archive N" — Move to the specified location (new, shortlist, or archive). Confirm briefly.
  • "Show N" — Fetch full content using mcp__readwise__reader_get_document_details. If the document is 3 mins or under, show the full content verbatim — no summary. If over 3 mins, give a richer summary with why-read/why-skip reasoning. Then re-present the options.
  • "Read N" — Provide the Reader link (https://read.readwise.io/read/{id}) so they can open it directly.
  • "Stop" / "done" — End the session with a brief summary of what was processed (how many seen, how many pulled).

Transitions

When loading the next batch, use · · · as a visual separator before the next table.

You are building an interactive 2D force-graph visualization of the user's Readwise highlights, showing how ideas connect across books, articles, and other sources. Think Obsidian's graph view, but for highlights.

Readwise Access

Check if Readwise MCP tools are available (e.g. mcp__readwise__readwise_list_highlights). If they are, use them throughout. If not, use the equivalent readwise CLI commands instead.

Process

Step 1: Fetch Highlights

Open with:

Highlight Graph · Readwise

I'll pull your recent highlights, find connections between them, and build a graph you can explore. Give me a moment.

Fetch the user's most recent highlights using readwise_list_highlights with page_size=100. Fetch 2 pages (200 highlights) for a good starting graph. Each page returns highlights from most recent to least recent — use page=1, then page=2.

Step 2: Prepare Highlight Data

Parse the API responses and build a JSON array of highlights. Each highlight needs:

{
  "id": "12345",
  "text": "The actual highlight text...",
  "note": "User's note if any",
  "book_id": 58741401,
  "source_title": "The Goal",
  "source_author": "Eliyahu Goldratt",
  "url": "https://..."
}

Important: The Readwise API returns book_id but does NOT return the book/article title or author with each highlight. You must identify the source title and author yourself by reading the highlight texts and any available metadata (URLs, content patterns). Group highlights by book_id and infer the source from context. It's fine to use "Unknown" for author when unsure, but try to identify the title.

Write this array to a temp file: /tmp/highlights.json

Step 3: Initial Render (No Connections)

Write an empty connections file and run the build script to give the user something to look at immediately:

echo '[]' > /tmp/connections.json
python3 SKILL_DIR/build_graph.py --highlights /tmp/highlights.json --connections /tmp/connections.json --output highlight-graph.html
open highlight-graph.html

Tell the user:

Graph is open with {N} highlights across {N} sources. Finding connections between ideas now...

Step 4: Find Cross-Source Connections

Launch parallel subagents (3-5 agents) to find semantic connections between highlights from different sources. Each agent should analyze a batch of highlights and return connections.

Batching strategy:

  1. Group highlights by source (book_id).
  2. Split sources into batches of ~8 sources each.
  3. For each batch pair (including within-batch), launch an agent with the highlight texts from those sources.
  4. Each agent should find 5-10 genuine conceptual connections — shared themes, ideas, or language across different sources.

Each agent should return a JSON array of connections:

[
  {
    "a_id": "12345",
    "b_id": "67890",
    "label": "Feedback loops",
    "why": "Both highlights discuss how tight feedback loops improve quality"
  }
]

Quality over quantity. Only create connections when the link is real and would be interesting. 15-30 total cross-source connections for 200 highlights is ideal.

Step 5: Rebuild with Connections

Merge all agent results into a single connections JSON array, write to /tmp/connections.json, and re-run the build script:

python3 SKILL_DIR/build_graph.py --highlights /tmp/highlights.json --connections /tmp/connections.json --output highlight-graph.html
open highlight-graph.html

Present a summary:

Built a graph of {N} highlights across {N} sources, with {N} connections between ideas.

A few interesting connections I found:

  • "{highlight A snippet}" ↔ "{highlight B snippet}" — {connection label}
  • ...

The graph is open in your browser. Want to add more highlights?

Step 6: Iterate

  • More highlights: Fetch additional pages (page=3, page=4, etc.), re-run source identification, find new connections, rebuild.
  • Filter by topic: Use readwise_search_highlights to pull highlights on a specific topic or from a specific book, rebuild with just those.

The Build Script

build_graph.py (in this skill's directory) handles all the visualization logic. It takes two JSON files and outputs a self-contained HTML file:

python3 build_graph.py --highlights highlights.json --connections connections.json --output output.html

highlights.json: Array of {id, text, note, book_id, source_title, source_author, url} connections.json: Array of {a_id, b_id, label, why}

The script handles:

  • Deduplication and filtering of highlights
  • Color assignment per source (rose-pine palette)
  • Same-source full pairwise connectivity (all highlights from same book linked)
  • Cross-source semantic connections (dashed purple edges with particles)
  • Interactive sidebar panel with connected ideas and same-book highlights
  • Label overlap prevention
  • Screen-relative text scaling (consistent size at any zoom level)
  • Source legend with click-to-filter
  • Hover isolation and selection persistence

The output is a single HTML file using force-graph from CDN. No server needed — just open in a browser.

SKILL_DIR

Replace SKILL_DIR in commands above with the actual path to this skill's directory (where build_graph.py lives).

You are generating a beautiful standalone HTML page showing what the user is currently reading and has recently read. The output is a single HTML file they can open in a browser or host on their personal site.

Readwise Access

Check if Readwise MCP tools are available (e.g. mcp__readwise__reader_list_documents). If they are, use them throughout (and pass this context to the subagent). If not, use the equivalent readwise CLI commands instead (e.g. readwise list, readwise read <id>). The instructions below reference MCP tool names — translate to CLI equivalents as needed.

Process

Launch a Task subagent to fetch all the data and generate the HTML file. The subagent should:

1. Fetch Data

Run ALL of these in parallel:

  • Shortlist: mcp__readwise__reader_list_documents with location="shortlist", limit=50, response_fields=["title", "author", "category", "reading_progress", "first_opened_at", "last_opened_at", "image", "url", "site_name", "word_count", "saved_at"]
  • Later: mcp__readwise__reader_list_documents with location="later", limit=50, response_fields=["title", "author", "category", "reading_progress", "first_opened_at", "last_opened_at", "image", "url", "site_name", "word_count", "saved_at"]
  • Inbox: mcp__readwise__reader_list_documents with location="new", limit=50, response_fields=["title", "author", "category", "reading_progress", "first_opened_at", "last_opened_at", "image", "url", "site_name", "word_count", "saved_at"]
  • Archive page 1: mcp__readwise__reader_list_documents with location="archive", limit=50, response_fields=["title", "author", "category", "reading_progress", "last_opened_at", "image", "url", "site_name", "saved_at", "word_count"]

2. Paginate Archive Deeply

After the first archive fetch, use nextPageCursor to keep fetching more pages (limit=50 each). Fetch at least 6 more pages (~350 total docs) so the heatmap covers 6 months of reading activity. Keep paginating until the oldest last_opened_at is 6+ months ago OR pages are exhausted.

3. Categorize

From the fetched data, build two lists:

  • Currently Reading: Items from shortlist, later, or inbox where reading_progress is between 0.05 and 0.99 (started but not finished). Sort by last_opened_at descending.
  • Recently Read: Items from archive where reading_progress > 0.9 (actually finished). Sort by last_opened_at descending. Group by month. Show as many months as the data covers.

Also collect ALL last_opened_at dates from archive items with reading_progress > 0.9 for the heatmap.

There is no "Up Next" section. Only show things the user is reading or has read.

4. Generate HTML

Create a now-reading/ directory in the current working directory (if it doesn't exist) and write the HTML file to now-reading/index.html.

Design direction: Warm, sepia-toned, editorial. Think personal reading log, not media dashboard.

Fonts: Google Fonts — Newsreader (serif, for headings) + DM Sans (sans, for body). Include via <link> tag.

Color palette (CSS variables):

--bg: #f6f1eb          (warm parchment background)
--surface: #ede6dc     (card/heatmap empty cell background)
--surface-hover: #e4dbd0
--border: #d9d0c4
--text: #4a4239        (main body text)
--text-muted: #8a7e72
--text-dim: #b0a597
--heading: #2c251e
--accent: #a0724a      (warm brown — progress bars, active states)
--accent-dim: rgba(160, 114, 74, 0.12)

Layout: Max-width 760px, centered. Responsive.

Sections in order:

  1. Header: "What I'm reading" in Newsreader, light weight, large. Subtitle: "Powered by Readwise Reader" with accent-colored link.

  2. Currently Reading — section label in small caps. Gallery of cards using CSS grid (repeat(auto-fill, minmax(160px, 1fr))) so they fill the container. Each card:

    • aspect-ratio: 3/2, rounded corners, hover lift effect
    • Cover image if available (image field). Gradient placeholder if not (hash title → hue).
    • Dark gradient overlay at bottom with white title + author
    • Progress bar at card bottom: 5px tall track (dark semi-transparent) with accent-colored fill
    • Cards link to the Reader URL
  3. Reading Activity — GitHub-style heatmap filling full container width. Use CSS flex with flex: 1 on weeks and cells so it stretches. Warm amber color scale (rgba(160, 114, 74, 0.2/0.4/0.65/1.0)). Month labels above, day-of-week labels (Mon/Wed/Fri) on left. Show 6 months.

  4. Recently Read — Category filter pills (All, Articles, Books, Tweets, RSS, Email) with JS toggle. Then entries grouped by month (e.g., "FEBRUARY 2026" in small caps). Each entry as a row:

    • Date on left (tabular nums, muted)
    • Category emoji (📄 article, 📚 book, 🐦 tweet, 📰 rss, ✉️ email, 🎬 video, 🎙 podcast, 📑 pdf)
    • Title (linked, medium weight) + author/source (dim, smaller)

Styling notes:

  • All CSS in a <style> tag with CSS variables
  • Subtle page-load fade-up animation on sections
  • Divider lines between sections (1px solid var(--border))
  • Responsive: 2-column card grid on mobile

5. Return

Return the absolute path to the generated HTML file and a summary: how many currently reading, how many recently read, date range of activity data.

After Subagent Returns

  1. Tell the user the file was generated and where it is
  2. Offer to open it in their browser: open now-reading/index.html
  3. Ask if they want to adjust anything

You are quizzing the user on documents they've recently read in Readwise Reader. Follow this process carefully.

Readwise Access

Check if Readwise MCP tools are available (e.g. mcp__readwise__reader_list_documents). If they are, use them throughout. If not, use the equivalent readwise CLI commands instead (e.g. readwise list, readwise read <id>, readwise search <query>). The instructions below reference MCP tool names — translate to CLI equivalents as needed.

Setup

  1. Check for persona file. Read reader_persona.md in the current working directory if it exists. Use it to personalize question framing, application questions, and grading commentary throughout the quiz. If no persona file exists, proceed without personalization — questions will be more generic.

  2. Welcome the user. Open with a brief, friendly introduction:

    Quiz · Readwise Reader

    I'll find something you've recently read and quiz you on it — one question at a time, graded like a smart colleague who also read the piece.

    (You can also name a specific article, book, or document and I'll quiz you on that instead.)

  3. Find a document to quiz on. The user may provide a document in one of these ways:

    If they give a specific document (title, URL, or ID) — use mcp__readwise__reader_search_documents or mcp__readwise__reader_list_documents with id to find it.

    If they say "quiz me" with no specific document — find recently read material:

    • Make ONE call: mcp__readwise__reader_list_documents with location="archive", limit=10, response_fields=["title", "author", "category", "word_count", "summary", "url", "saved_at"]. Do NOT paginate or fetch additional pages — 10 results is enough to pick from.
    • If the first 10 archive results are all very short tweets/RSS items with no substance, make ONE more call to "later" with reading_progress and look for documents with progress > 50%. That's it — two calls maximum.
    • Present 3-5 candidates as a table, then ask the user to pick:
    #TitleAuthorLength
    1.........

    Or if there's a clear best pick, confirm: "Want me to quiz you on [title]?"

  4. Fetch the full document. Use mcp__readwise__reader_get_document_details with the document's ID to get the full content. Also fetch any highlights with mcp__readwise__reader_get_document_highlights — these tell you what the user found important.

  5. Read the document. Understand its core arguments, key claims, structure, and nuances. Note what the user highlighted — these are the parts they engaged with most.

Quiz Flow

Present questions one at a time. Wait for the user's answer before moving on.

Opening

Tell the user what you're quizzing them on:

Quiz: [Title] by [Author] [Category] · [word count or read time]

[1-2 sentence description of what the piece argues/covers]

I'll ask [3-5] questions. Ready?

Question Types

Mix these types based on the document. Not every quiz needs all types.

  • "What's the core argument?" — Tests if they got the main point
  • "How would you apply this to [their domain]?" — Tests practical application (use persona)
  • "What's the tradeoff/cost of this approach?" — Tests critical thinking
  • "What did the author miss or hand-wave?" — Tests deep reading
  • "If you had to bet on [prediction], would you? Why?" — Tests synthesis
  • "How does this connect to [another thing they've read]?" — Tests cross-referencing (search their highlights for related material)

Personalization

If the persona file exists, frame questions around their world:

  • Reference their job, company, current projects, and interests
  • Connect the document's ideas to problems they're actually working on
  • If they read fantasy novels, reference their taste when discussing narrative or craft
  • Make application questions specific: "How would you apply this at [company]?" not "How would you apply this?"

Question Count

  • Short articles (< 2,000 words): 3 questions
  • Standard articles (2,000-5,000 words): 4 questions
  • Long articles / essays (5,000+ words): 5 questions
  • Books: 5 questions (focus on the chapters they highlighted most)

Grading

After each answer:

  1. State the grade clearly: Grade: B+
  2. Acknowledge what they got right — be specific
  3. Fill in what they missed or could go deeper on
  4. Quote the document if relevant to reinforce the point
  5. Transition to next question

Grading Scale

  • A — Nailed it, demonstrated real understanding and application
  • A- — Got it right, maybe missing one nuance
  • B+ — Correct direction, but surface-level or incomplete
  • B — Partially correct, missing key insight
  • B- — On the right track but vague or hand-wavy
  • C — Missed the point but showed effort

Grading Style

Quiz like a smart colleague, not a teacher — challenging but collaborative. Be direct, no fluff. Be honest about what they got right and what they missed. Quote the source material when it sharpens the point.

Final Score

After all questions, provide:

  1. Overall score (e.g., "Final Score: B+")
  2. One-line summary of what they understood well
  3. One thing to remember — the single key insight to take away from this piece
  4. Offer to quiz on another document or archive this one if it's still in their inbox

Tone

  • Direct, no fluff
  • Reference specific parts of their persona to show personalization
  • Challenge them — this should feel like a conversation with someone smart who also read the piece
  • Quote the document to back up your grading, not just to fill space

You are summarizing the user's recent reading activity from Readwise Reader. Follow this process carefully.

Readwise Access

Check if Readwise MCP tools are available (e.g. mcp__readwise__reader_list_documents). If they are, use them throughout. If not, use the equivalent readwise CLI commands instead (e.g. readwise list, readwise read <id>, readwise highlights <id>). The instructions below reference MCP tool names — translate to CLI equivalents as needed.

Setup

  1. Check for persona file. Read reader_persona.md in the current working directory if it exists. Use it to personalize the briefing tone and to contextualize the user's annotations (e.g. connecting highlights to their known interests). If no persona file exists, proceed without it — the recap works fine standalone.

  2. Determine time window. Parse the argument as a number of days. Default to 1 (last 24 hours) if no argument is given.

/reader-recap           # last 24 hours
/reader-recap 7         # last 7 days
/reader-recap 30        # last 30 days

Step 1: Fetch Recent Documents

Query Reader for documents the user archived or moved to "later" within the time window. Run both calls in parallel:

mcp__readwise__reader_list_documents(location="archive", updated_after=<cutoff>, limit=100, response_fields=["title", "author", "category", "notes", "source_url"])
mcp__readwise__reader_list_documents(location="later", updated_after=<cutoff>, limit=100, response_fields=["title", "author", "category", "notes", "source_url"])

Combine and deduplicate results by document ID.

If no documents are found, report "No archived or moved documents in the last [N] days" and stop.

Step 2: Get Highlights

For each document returned, fetch highlights:

mcp__readwise__reader_get_document_highlights(document_id=<id>)

After fetching, split documents into three groups:

  • Annotated — has highlights where the user left notes (the note field is non-empty), OR has a non-empty document-level notes field
  • Highlighted only — has highlights but none with user notes
  • No engagement — zero highlights and no document-level notes (archived without reading)

Step 3: Classify Annotations

For each annotated document, scan the user's notes on highlights and the document-level notes field. Flag anything actionable:

FlagPattern
QuestionContains "?" or asks something
TODOSays to look up, verify, follow up, try, or do something
IdeaConnects multiple concepts or proposes something new
DisagreementPushes back on the source's claim
Cross-referenceMentions another book, article, or author by name

Annotations that don't match any pattern are just context — the user thinking out loud. Still include them in the briefing.

Step 4: Write the Briefing

Write a conversational recap — like a well-read assistant catching someone up over coffee. Warm, concise, and useful. Not a data dump.

Structure:

  1. Opening line — a one-sentence overview of the time period.

    "You had a busy week — 12 articles and a book, mostly history and AI stuff."

    "Quiet day — just two articles, but you had a lot to say about one of them."

  2. Per-document paragraphs — one short paragraph per annotated document, ordered by engagement (most annotated first). Each paragraph should naturally weave together:

    • What the piece was about (1 sentence)
    • How much the user highlighted (folded into the flow, not as a stat line)
    • The most interesting annotations, especially actionable ones — paraphrase the user's notes conversationally: "You had a question about whether this applies to mammals too." "You noted you want to try this workflow yourself." "You pushed back on the author's claim about pricing."
    • If the user left a document-level note, lead with it — it's usually the overall reaction
  3. Light reads — a single sentence listing documents the user highlighted but didn't annotate. "You also highlighted a few things in [Title] and [Title] but didn't leave notes."

  4. Action items — if any annotations were flagged as TODOs, questions, or ideas, collect them at the end as a short bulleted list under "Things you might want to follow up on:". Skip this section entirely if nothing is actionable.

Example output:

Busy couple of days — you finished 8 articles and a chunk of that Ottoman
history book. Most of your attention went to the logistics stuff.

You were really into Sarah Chen's piece on supply chain resilience. 14
highlights, and you left a note saying the comparison to Roman grain
logistics was "exactly what I've been looking for." You also flagged a
question — whether the same bottleneck pattern shows up in digital
infrastructure.

The Ottoman book got 9 new highlights across three chapters. Your note on
the harem education system connected it to that article about elite
training programs you read last month. You also marked a claim about
succession rates that you want to verify.

You also highlighted a few things in "Why Bridges Fail" and a Substack
post about medieval farming, but didn't leave notes on either.

**Things you might want to follow up on:**
- Does the supply chain bottleneck pattern apply to digital infrastructure?
- Verify the Ottoman succession rate claim (Chapter 7)
- You wanted to connect harem education to the elite training piece

Tone rules:

  • Second person ("you read", "you noted"), not third person
  • Contractions are fine
  • No bullet-point lists for the main body — prose paragraphs only
  • Keep it skimmable — short paragraphs, one idea each
  • Don't editorialize on the content itself — just report what the user did and said
  • The action items list at the end IS bulleted — that's the one exception
  • If the persona file exists, use it to add context (e.g. "this connects to your interest in X")

Notes

  • This skill is read-only. It doesn't move, tag, or modify any documents.
  • The "archive" and "later" locations catch most finished reading. Documents still in "feed" or "new" are works in progress and aren't included.
  • Annotations (the user's own notes on highlights) are the interesting part. Raw highlights without notes are counted but not shown individually.
  • For large time windows (30 days), there may be many documents. Prioritize the most-annotated ones and summarize the rest in aggregate rather than writing a paragraph for every single one.

Readwise CLI

Use the readwise command to access the user's Readwise highlights and Reader documents. Readwise has two products:

  • Readwise — highlights from books, articles, podcasts, and more. Includes daily review and spaced repetition.
  • Reader — a read-later app for saving and reading articles, PDFs, EPUBs, RSS feeds, emails, tweets, and videos.

Setup

If readwise is not installed:

npm install -g @readwise/cli

If not authenticated, ask the user for their Readwise access token (they can get one at https://readwise.io/access_token), then run:

readwise login-with-token <token>

Discovering Commands

Every command supports --help for full option details:

readwise --help
readwise reader-search-documents --help
readwise readwise-list-highlights --help

Add --json to any command for machine-readable output. Use --refresh to force-refresh cached data.

Reader Commands

Searching documents

# Semantic search across all saved documents
readwise reader-search-documents --query "spaced repetition"

# Search only articles saved for later
readwise reader-search-documents --query "machine learning" --category-in article --location-in later,shortlist

# Search by author within the inbox
readwise reader-search-documents --query "AI" --author-search "Simon Willison" --location-in new

# Search documents published after a date
readwise reader-search-documents --query "transformers" --published-date-gt 2024-01-01

Browsing documents

# List 10 most recent inbox items (minimal fields to save tokens)
readwise reader-list-documents --location new --limit 10 --response-fields title,author,summary,word_count,category,saved_at

# List archived articles tagged "research"
readwise reader-list-documents --location archive --tag research --category article

# List unseen documents in the inbox
readwise reader-list-documents --location new --seen false

# List RSS feed items
readwise reader-list-documents --location feed --limit 20 --response-fields title,author,summary,site_name

# Get a specific document by ID
readwise reader-list-documents --id <document_id>

Locations: new (inbox), later, shortlist, archive, feed. When the user says "inbox", use new.

Reading and highlighting

# Get full document content as Markdown
readwise reader-get-document-details --document-id <id>

# Get all highlights on a document
readwise reader-get-document-highlights --document-id <id>

# Highlight a passage (html-content must match the document's HTML exactly)
# Get the HTML first via reader-list-documents with --response-fields html_content
readwise reader-create-highlight --document-id <id> --html-content "<p>The exact passage to highlight</p>"

# Highlight with a note and tags
readwise reader-create-highlight --document-id <id> --html-content "<p>Key insight</p>" --note "Connects to spaced repetition research" --tags review,concept

Saving documents

# Save a URL — Reader scrapes it automatically
readwise reader-create-document --url "https://example.com/article"

# Save with metadata
readwise reader-create-document --url "https://example.com" --title "Great Article" --tags research,ai --notes "Recommended by Alice"

# Save raw Markdown content (provide a unique URL as identifier)
readwise reader-create-document --title "Meeting Notes" --markdown "# Notes from today..." --url "https://me.com#notes-march-2025"

Organizing

# Move documents between locations (max 50 per call)
readwise reader-move-documents --document-ids <id1>,<id2> --location archive
readwise reader-move-documents --document-ids <id> --location later

# Bulk mark documents as seen
readwise reader-bulk-edit-document-metadata --documents '[{"document_id": "<id>", "seen": true}]'

# Bulk update metadata (title, author, tags, summary, etc.)
readwise reader-bulk-edit-document-metadata --documents '[{"document_id": "<id>", "title": "Better Title", "tags": ["ai", "research"]}]'

# Tags
readwise reader-list-tags
readwise reader-add-tags-to-document --document-id <id> --tag-names important,research
readwise reader-remove-tags-from-document --document-id <id> --tag-names old-tag

# Highlight tags and notes
readwise reader-add-tags-to-highlight --document-id <id> --highlight-document-id <hid> --tag-names concept
readwise reader-remove-tags-from-highlight --document-id <id> --highlight-document-id <hid> --tag-names old-tag
readwise reader-set-highlight-notes --document-id <id> --highlight-document-id <hid> --notes "Updated note"

Exporting

# Export all documents as a ZIP of Markdown files (async)
readwise reader-export-documents
readwise reader-get-export-documents-status --export-id <id>

# Delta export — only docs updated since last export
readwise reader-export-documents --since-updated "2024-01-01T00:00:00Z"

Readwise Commands

Searching highlights

# Semantic search across all highlights
readwise readwise-search-highlights --vector-search-term "learning techniques"

# Search with full-text filter on a specific field
readwise readwise-search-highlights --vector-search-term "memory" --full-text-queries '[{"field_name": "document_title", "search_term": "psychology"}]'

Full-text query fields: document_author, document_title, highlight_note, highlight_plaintext, highlight_tags.

Browsing highlights

# List 20 most recent highlights
readwise readwise-list-highlights --page-size 20

# Highlights from a specific book
readwise readwise-list-highlights --book-id <id>

# Highlights from the last month
readwise readwise-list-highlights --highlighted-at-gt "2025-02-01T00:00:00Z"

Creating and editing highlights

# Create a highlight (matched to a book by title/author, or goes into "Quotes")
readwise readwise-create-highlights --highlights '[{"text": "The key insight here", "title": "Book Title", "author": "Author Name"}]'

# Create multiple highlights at once
readwise readwise-create-highlights --highlights '[{"text": "First quote", "title": "Book A"}, {"text": "Second quote", "title": "Book B"}]'

# Update a highlight — text, note, color, tags
readwise readwise-update-highlight --highlight-id <id> --note "New note" --add-tags concept,review --color blue

# Delete a highlight
readwise readwise-delete-highlight --highlight-id <id>

Colors: yellow, blue, pink, orange, green, purple.

Daily review

# Get today's spaced repetition review
readwise readwise-get-daily-review

Returns highlights selected by the spaced repetition algorithm plus a URL for interactive review.

Example Workflows

Triage the inbox: List recent saves, read each one, decide what's worth the user's time.

readwise reader-list-documents --location new --limit 10 --response-fields title,author,summary,word_count,category,saved_at
readwise reader-get-document-details --document-id <id>
readwise reader-move-documents --document-ids <id> --location later    # worth reading
readwise reader-move-documents --document-ids <id> --location archive  # skip

Search across everything: Find all content on a topic across both highlights and documents.

readwise reader-search-documents --query "spaced repetition"
readwise readwise-search-highlights --vector-search-term "spaced repetition"

Quiz on a recent read: Find a finished document, get its content and highlights, quiz the user.

readwise reader-list-documents --location archive --limit 10 --response-fields title,author,summary,word_count
readwise reader-get-document-details --document-id <id>
readwise reader-get-document-highlights --document-id <id>

Catch up on RSS: Browse feed items, surface the best ones, mark the rest as seen.

readwise reader-list-documents --location feed --limit 20 --response-fields title,author,summary,word_count,site_name
readwise reader-bulk-edit-document-metadata --documents '[{"document_id": "<id>", "seen": true}]'
readwise reader-move-documents --document-ids <id> --location later

Save and annotate: Save a URL, highlight key passages, tag and organize.

readwise reader-create-document --url "https://example.com/article" --tags research
readwise reader-create-highlight --document-id <id> --html-content "<p>Key passage here</p>" --note "This connects to..."
readwise reader-add-tags-to-document --document-id <id> --tag-names important

Build a reading recap: See what you've finished and highlighted recently.

readwise reader-list-documents --location archive --updated-after "2025-03-10T00:00:00Z" --response-fields title,author,word_count,reading_progress
readwise reader-get-document-highlights --document-id <id>
readwise readwise-list-highlights --highlighted-at-gt "2025-03-10T00:00:00Z" --page-size 50

Readwise MCP

Use the Readwise MCP tools to access the user's Readwise highlights and Reader documents. Readwise has two products:

  • Readwise — highlights from books, articles, podcasts, and more. Includes daily review and spaced repetition.
  • Reader — a read-later app for saving and reading articles, PDFs, EPUBs, RSS feeds, emails, tweets, and videos.

Setup

Add the Readwise MCP server to your client's configuration:

{
  "readwise": {
    "type": "http",
    "url": "https://mcp2.readwise.io/mcp"
  }
}

The server handles authentication via OAuth — the user will be prompted to authorize on first use.

Tool Reference

All tools are prefixed with mcp__readwise__. Each tool name maps directly to a Readwise or Reader API action.

Reader Tools

Searching documents

reader_search_documents(query="spaced repetition")

Hybrid search (semantic + keyword) across all saved documents. Combine with filters to narrow results:

# Search articles saved for later
reader_search_documents(query="machine learning", category_in=["article"], location_in=["later", "shortlist"])

# Search by author
reader_search_documents(query="AI agents", author_search="Simon Willison")

# Search within a date range
reader_search_documents(query="transformers", published_date_gt="2024-01-01")

# Search by tags
reader_search_documents(query="productivity", tags_in=["research"])

Other filters: title_search, summary_search, note_search, url_search, source_search, document_id, limit (default 20, max 100).

Browsing documents

# List 10 most recent inbox items with minimal fields
reader_list_documents(location="new", limit=10, response_fields=["title", "author", "summary", "word_count", "category", "saved_at"])

# Archived articles with a specific tag
reader_list_documents(location="archive", tag=["research"], category="article")

# Unseen inbox items
reader_list_documents(location="new", seen=false)

# RSS feed items
reader_list_documents(location="feed", limit=20, response_fields=["title", "author", "summary", "site_name"])

# Get a specific document by ID
reader_list_documents(id="<document_id>")

# Paginate through results
reader_list_documents(location="later", limit=10, page_cursor="<cursor_from_previous_response>")

Locations: new (inbox), later, shortlist, archive, feed. When the user says "inbox", use new. Only use feed when the user explicitly asks about RSS/feeds.

Use response_fields to limit returned data and save tokens. The id field is always included. Available fields: url, title, author, source, category, location, tags, site_name, word_count, reading_time, created_at, updated_at, published_date, summary, image_url, content, source_url, notes, parent_id, reading_progress, first_opened_at, last_opened_at, saved_at, last_moved_at, html_content, is_deleted.

Tip: unseen documents have first_opened_at=null. Mark as seen via reader_bulk_edit_document_metadata.

Reading and highlighting

# Get full document details including Markdown content
reader_get_document_details(document_id="<id>")

# Get all highlights on a document
reader_get_document_highlights(document_id="<id>")

# Create a highlight — html_content must match the document's HTML exactly
# Get the HTML via reader_list_documents with response_fields=["html_content"]
reader_create_highlight(document_id="<id>", html_content="<p>The exact passage to highlight</p>")

# Highlight with a note and tags
reader_create_highlight(document_id="<id>", html_content="<p>Key insight</p>", note="Connects to spaced repetition", tags=["review", "concept"])

Saving documents

# Save a URL — Reader scrapes it automatically
reader_create_document(url="https://example.com/article")

# Save with metadata and tags
reader_create_document(url="https://example.com", title="Great Article", tags=["research", "ai"], notes="Recommended by Alice")

# Save raw Markdown content (provide a unique URL as identifier)
reader_create_document(title="Meeting Notes", markdown="# Notes from today...", url="https://me.com#notes-march-2025")

Organizing

# Move documents between locations (max 50 per call)
reader_move_documents(document_ids=["<id1>", "<id2>"], location="archive")

# Bulk mark documents as seen
reader_bulk_edit_document_metadata(documents=[{"document_id": "<id>", "seen": true}])

# Bulk update metadata
reader_bulk_edit_document_metadata(documents=[{"document_id": "<id>", "title": "Better Title", "tags": ["ai", "research"]}])

Note: reader_move_documents and reader_bulk_edit_document_metadata share a rate limit of 20 calls/minute. Batch document IDs into fewer calls.

Tags

# List all tags
reader_list_tags()

# Add tags to a document
reader_add_tags_to_document(document_id="<id>", tag_names=["important", "research"])

# Remove tags from a document
reader_remove_tags_from_document(document_id="<id>", tag_names=["old-tag"])

# Add tags to a highlight
reader_add_tags_to_highlight(document_id="<id>", highlight_document_id="<hid>", tag_names=["concept"])

# Remove tags from a highlight
reader_remove_tags_from_highlight(document_id="<id>", highlight_document_id="<hid>", tag_names=["old-tag"])

# Set notes on a highlight (pass null to clear)
reader_set_highlight_notes(document_id="<id>", highlight_document_id="<hid>", notes="My updated note")

Exporting

# Export all documents as a ZIP of Markdown files (async — returns export_id)
reader_export_documents()

# Delta export — only docs updated since last export
reader_export_documents(since_updated="2024-01-01T00:00:00Z")

# Poll for completion
reader_get_export_documents_status(export_id="<id>")

Poll reader_get_export_documents_status until status is "completed", then use the download_url.

Readwise Tools

Searching highlights

# Semantic search across all highlights
readwise_search_highlights(vector_search_term="learning techniques")

# Search with full-text filter on a specific field
readwise_search_highlights(vector_search_term="memory", full_text_queries=[{"field_name": "document_title", "search_term": "psychology"}])

Full-text query fields: document_author, document_title, highlight_note, highlight_plaintext, highlight_tags.

Browsing highlights

# List 20 most recent highlights
readwise_list_highlights(page_size=20)

# Highlights from a specific book
readwise_list_highlights(book_id=12345)

# Highlights from the last month
readwise_list_highlights(highlighted_at_gt="2025-02-01T00:00:00Z")

# Paginate
readwise_list_highlights(page_size=100, page=2)

Creating and editing highlights

# Create a highlight (matched to a book by title/author, or goes into "Quotes")
readwise_create_highlights(highlights=[{"text": "The key insight here", "title": "Book Title", "author": "Author Name"}])

# Create multiple highlights at once
readwise_create_highlights(highlights=[{"text": "First quote", "title": "Book A"}, {"text": "Second quote", "title": "Book B", "note": "Great point"}])

# Update a highlight
readwise_update_highlight(highlight_id=12345, note="New note", add_tags=["concept", "review"], color="blue")

# Delete a highlight
readwise_delete_highlight(highlight_id=12345)

Colors: yellow, blue, pink, orange, green, purple.

Daily review

# Get today's spaced repetition review
readwise_get_daily_review()

Returns highlights selected by the algorithm plus a URL for interactive review.

Example Workflows

Triage the inbox: List recent saves, read each one, decide what's worth the user's time.

reader_list_documents(location="new", limit=10, response_fields=["title", "author", "summary", "word_count", "category", "saved_at"])
reader_get_document_details(document_id="<id>")
reader_move_documents(document_ids=["<id>"], location="later")     # worth reading
reader_move_documents(document_ids=["<id>"], location="archive")   # skip

Search across everything: Find all content on a topic — run both in parallel.

reader_search_documents(query="spaced repetition")
readwise_search_highlights(vector_search_term="spaced repetition")

Quiz on a recent read: Find a finished document, get its content and highlights.

reader_list_documents(location="archive", limit=10, response_fields=["title", "author", "summary", "word_count"])
reader_get_document_details(document_id="<id>")
reader_get_document_highlights(document_id="<id>")

Catch up on RSS: Browse feed items, surface the best ones, mark the rest as seen.

reader_list_documents(location="feed", limit=20, response_fields=["title", "author", "summary", "word_count", "site_name"])
reader_bulk_edit_document_metadata(documents=[{"document_id": "<id1>", "seen": true}, {"document_id": "<id2>", "seen": true}])
reader_move_documents(document_ids=["<id>"], location="later")

Save and annotate: Save a URL, highlight key passages, tag and organize.

reader_create_document(url="https://example.com/article", tags=["research"])
reader_create_highlight(document_id="<id>", html_content="<p>Key passage here</p>", note="This connects to...")
reader_add_tags_to_document(document_id="<id>", tag_names=["important"])

Build a reading recap: See what you've finished and highlighted recently.

reader_list_documents(location="archive", updated_after="2025-03-10T00:00:00Z", response_fields=["title", "author", "word_count", "reading_progress"])
reader_get_document_highlights(document_id="<id>")
readwise_list_highlights(highlighted_at_gt="2025-03-10T00:00:00Z", page_size=50)

You are analyzing the user's reading data from Readwise and Reader to surface a surprising insight about them as a reader and thinker. Follow this process carefully.

Readwise Access

Check if Readwise MCP tools are available (e.g. mcp__readwise__reader_list_documents). If they are, use them throughout. If not, use the equivalent readwise CLI commands instead (e.g. readwise list, readwise read <id>, readwise search <query>). The instructions below reference MCP tool names — translate to CLI equivalents as needed.

Process

1. Gather Data

Cast a wide net. Run ALL of these in parallel:

  • Recent highlights: mcp__readwise__readwise_list_highlights with limit=100
  • Highlight search 1: mcp__readwise__readwise_search_highlights with a broad term like "important" or "interesting"
  • Highlight search 2: mcp__readwise__readwise_search_highlights with another broad term like "surprised" or "changed my mind"
  • Tags: mcp__readwise__reader_list_tags
  • Archived documents: mcp__readwise__reader_list_documents with location="archive", limit=50, response_fields=["title", "author", "category", "tags", "word_count", "reading_progress", "saved_at", "last_opened_at"]
  • Shortlist documents: mcp__readwise__reader_list_documents with location="shortlist", limit=50, response_fields=["title", "author", "category", "tags", "word_count", "reading_progress", "saved_at"]

Then paginate the archive at least 2-3 more pages to get a larger sample.

2. Analyze

Look across ALL the data for patterns, contradictions, and surprises. Consider:

  • Hidden obsessions: Topics that show up way more than expected across highlights and saves
  • Contradictions: Are they saving/highlighting opposing viewpoints? Do their reading interests conflict with each other in interesting ways?
  • Reading behavior patterns: Do they save more than they read? Highlight differently across categories? Binge certain authors?
  • Evolving interests: Has their reading shifted over time? What are they moving toward or away from?
  • Blind spots: What's conspicuously absent given their other interests?
  • Unexpected connections: Do two seemingly unrelated interests actually share a deeper thread?
  • What they highlight vs what they save: Do the highlights reveal different interests than the documents they save?

3. Deliver the Surprise

Present ONE genuinely surprising insight. Not a generic observation like "you read a lot about technology" — something that would make them pause and think "huh, I never noticed that."

Format:

Here's something you might not know about yourself:

[The surprising insight — 2-3 sentences, specific and grounded in their actual data]

Then back it up with evidence:

  • Quote specific highlights that support the insight
  • Reference specific documents/authors
  • Show the pattern across multiple data points

4. Go Deeper

After delivering the insight, offer:

  • "Want me to dig into this further?"
  • "I noticed a few other patterns too — want to hear them?"
  • "Want me to find documents in your library that connect to this theme?"

Tone

  • Genuinely curious and observant, like a perceptive friend who noticed something you didn't
  • Specific — always reference real data, never generic platitudes
  • Surprising — if the insight feels obvious, dig deeper until you find something that isn't

You are triaging the user's Readwise Reader inbox. Follow this process carefully.

Readwise Access

Check if Readwise MCP tools are available (e.g. mcp__readwise__reader_list_documents). If they are, use them throughout. If not, use the equivalent readwise CLI commands instead (e.g. readwise list, readwise read <id>, readwise move <id> <location>). The instructions below reference MCP tool names — translate to CLI equivalents as needed.

Setup

  1. Check for persona file. Read reader_persona.md in the current working directory if it exists. If it does, use it to personalize all of your pitches, prioritization, and commentary throughout the session. Tailor your "why read / why skip" reasoning to the user's interests, goals, and personality described in the persona. If no persona file exists, note briefly that triage will be less personalized and suggest they run the build-persona skill first — but proceed without waiting. If you do show this message, add · · · after it before the inbox overview.

  2. Fetch inbox documents. Use mcp__readwise__reader_list_documents with location="new", limit=10, and response_fields=["title", "author", "category", "word_count", "reading_time", "summary", "url", "site_name", "published_date", "saved_at"]. Documents come back most-recently-saved first, which is what we want.

  3. Give an inbox overview. Format it exactly like this:

📬 Reader Inbox · {count} documents

Welcome! Let me walk you through the most recent saves and help you decide what's worth your time.

{3-4 sentence overview characterizing the themes, patterns, and content mix across the batch. Note any clusters of related reads or interesting contrasts. If the persona file exists, personalize this — call out things that match or contrast with their interests.}

Let's start with the most recent thing in your inbox:

· · ·

Triage Loop

Present documents one at a time, starting from the most recently saved. For each document, use this exact format:

Document Card

Render an ASCII box in a code block. Pad all lines to the same width so the right │ border aligns. Use this structure:

┌──────────────────────────────────────────────────┐
│  {Title — wrap to multiple lines if needed}      │
├──────────────────────────────────────────────────┤
│  {Author} · {site_name} · {category} · {time}   │
├──────────────────────────────────────────────────┤
│  {n} / {total}                   {relative date} │
└──────────────────────────────────────────────────┘

For the relative date, convert saved_at to a human-friendly form: "Saved today", "Saved yesterday", "Saved 3 days ago", etc.

The Pitch

After the card, provide:

  • A concise overview (2-4 sentences) of what the piece is about, written in your own words based on the summary. Don't just restate the summary bullets — synthesize into a narrative.
  • "Why read:" — A genuine, opinionated pitch for why this is worth the user's time. Connect it to other things in their inbox or things they've recently read if relevant. If the persona file exists, connect it to their interests/goals.
  • "Why skip:" — An honest reason they might not need to read it. Be real, not dismissive.

The Options

Present exactly these options:

  • Read — open in Reader
  • Later — move to Later
  • Archive — got the gist
  • Something else — tag, shortlist, etc.

(If you read it, let me know and I'll archive it for you)

Transitions

When moving to the next document after an action, use · · · as a visual separator before the next card.

Handling Responses

  • "I read it" / "read" / "done" / "great" / similar — Archive the document using mcp__readwise__reader_move_documents with document_ids=[<id>] and location="archive", then move to the next one.
  • "Later" — Move document to later location and move to the next one.
  • "Archive" / "skip" — Archive the document and move to the next one.
  • "Something else" — Ask what they'd like to do (tag, shortlist, etc.), do it, then move on.
  • "Tell me more" / "What's it about?" / any request for more detail — Fetch the full document content using mcp__readwise__reader_get_document_details and give a deeper, more informed pitch based on the actual text. Then re-present the options.
  • "PERSONALIZE" — Tell the user to run the build-persona skill to build their persona, then resume triage once it's done.

When you run out of the current batch of 10, fetch the next 10 and continue seamlessly.

MCP servers 1

Sponsors

Details

Marketplace
readwiseio/readwise-skills
Category
Community