# Readwise

> Use this skill to work with the Readwise Original API for creating, organizing, and reviewing highlights and books.

- **Type:** Skill
- **Install:** `agentstack add skill-ryanlyn-readwise-skill-readwise`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ryanlyn](https://agentstack.voostack.com/s/ryanlyn)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ryanlyn](https://github.com/ryanlyn)
- **Source:** https://github.com/ryanlyn/readwise-skill/tree/main/plugins/readwise/skills/readwise

## Install

```sh
agentstack add skill-ryanlyn-readwise-skill-readwise
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Readwise Original Skill

Use this skill to automate work with the Readwise "Original" API that powers highlight exports and metadata management.

## Quick start
1. Generate a token from https://readwise.io/access_token and store it in `READWISE_TOKEN`.
2. Use `uv run --project ${CLAUDE_PLUGIN_ROOT} python ${CLAUDE_PLUGIN_ROOT}/skills/readwise/scripts/readwise_client.py ...` instead of calling the API directly; it handles retries, pagination, rate-limit surfacing, `--dry-run`, and tagging rules.
3. Keep requests below the documented rate limit (currently 60 req/min). Batch operations and pause between pages when processing large libraries.

## Example workflows
- "Summarize my daily review and save highlights to a note" — uses `highlights review` to fetch today's highlights, then formats them
- "Find all highlights from Meditations and export as markdown" — uses `books` to find the book ID, then `highlights list` to fetch
- "Save this quote to my Readwise" — uses `highlight create` with the quote text

## CLI commands

Global options `--dry-run` and `--raw` can appear anywhere in the command.

- `uv run --project ${CLAUDE_PLUGIN_ROOT} python ${CLAUDE_PLUGIN_ROOT}/skills/readwise/scripts/readwise_client.py [--dry-run] [--raw] highlight create --text ... [--book-id ID] [--title ...] [--author ...] [--category ...] [--image-url ...] [--generated] [--tags t1,t2]`
  Creates a highlight or batch (`--bulk-file ndjson`). Use `--book-id` to target an existing book (the CLI resolves it to title/author/category for the API). **Always specify `--category`** when creating new sources—see "Category is critical" below. Use `--image-url` for cover images (recommended for `books` and `podcasts`, not needed for `articles` or `tweets`). If `--generated` is set, `.generated` is appended to tags and `location_type` defaults to `none`.
- `... [--dry-run] highlight update  [--title --note --tags --generated]` – partial updates.
- `... highlight show ` – fetch highlight details.
- `... highlight delete  [--yes]` – delete a highlight, `--yes` skips confirmation.
- `... highlights list [--book-id 123] [--tag focus] [--category books] [--updated-after 2026-02-01] [--limit 50]` – cursor-based listing. Dates are ISO format (e.g. `2026-02-01` or `2026-02-01T10:30:00Z`).
- `... highlights review` – fetches today's daily review highlights (no parameters; returns the curated spaced-repetition set).
- `... books [--title ...] [--author ...] [--limit N]` – search books by title/author (case-insensitive substring match).
- `... book ` – fetch a single book's metadata.
- `... auth validate` – confirms your token works by hitting the `/api/v2/auth/` endpoint.

Default output is human-readable markdown with only key fields. Use `--raw` to get full JSON with all fields.

## Disambiguating book matches

`books --title` performs a case-insensitive substring match and often returns multiple books with the same title. Readwise creates separate book entries per source (Kindle, API, supplemental, etc.), so duplicates are common. When multiple results come back, review them all and use judgement to determine whether they are duplicates of the same work or entirely separate books:

- **Duplicates** (same author, different sources): Readwise creates one entry per import source. A Kindle book and an API-created entry for the same work will share a title/author. Among duplicates, the entry with the most `num_highlights` is usually the primary one.
- **Distinct books**: Different authors or categories mean genuinely different works. Treat these as separate and ask the user which one they mean if the intent is ambiguous.

## Listing highlights for a book by name

1. Find the book ID: `... books --title "book name"`
2. If multiple results, review all entries to determine which are duplicates vs distinct books. For duplicates, query the entry with the most highlights. For distinct books, clarify with the user.
3. List its highlights: `... highlights list --book-id `

## Adding a highlight to an existing book
1. Search for the book: `... books --title "when breath becomes air"`
2. Note the book `id` from the output.
3. Create the highlight: `... highlight create --text "the verbatim quote" --book-id `
   The CLI looks up the book's title/author/category and injects them into the payload so the Readwise API matches the highlight to the correct book.
   Only add `--generated` if the text is a summary or paraphrase, not a direct quote.

## How Readwise matches sources

Readwise groups highlights into "books" (sources) using **(title, author, source_url)**. The API de-duplicates highlights by matching all four fields: **(title, author, source_url, text)**—including nulls.

**Critical**: All highlights from the same content—whether verbatim quotes or generated summaries—MUST use identical `(title, author, source_url)` values to be grouped together. Inconsistent attributes will scatter highlights across separate book entries.

- If you omit `--title`, highlights go into a generic "Quotes" book
- If you omit `--author`, it stays blank (or uses the URL domain if `source_url` is set)
- Use `--book-id` when adding to an existing book—the CLI fetches and injects the correct title/author/source_url

## Category is critical

**Always specify `--category` explicitly.** The API defaults to `articles` if `source_url` is present, otherwise `books`—but these defaults often miscategorize content. Valid categories: `books`, `articles`, `tweets`, `podcasts`.

| Content type | Category |
|--------------|----------|
| Physical/ebook | `books` |
| Blog post, web article | `articles` |
| Tweet/X post | `tweets` |
| Podcast episode | `podcasts` |
| **YouTube video** | `podcasts` |

**YouTube videos should use `podcasts`**, not `articles`. Readwise treats video content as podcast-like (time-based, spoken word). Using `articles` will cause display and organizational issues.

Mismatched categories create duplicate book entries and break the user's library organization. When in doubt, ask the user or check existing entries with `books --title`.

## Agent interaction rules
- **Always quote highlights in full**: Never reference a highlight in the abstract. When displaying or communicating about a highlight to the user, always include the full highlight text in its entirety as a quoted markdown block (using `>`).
- **Never save without confirmation**: Never save a highlight (create or update) without explicit user confirmation first. Draft the highlight, show it quoted, and wait for approval before calling the API.

## Data entry guidance
- **Generated snippets**: Use `--generated` ONLY for highlights that are NOT verbatim quotes from the source content—e.g., AI-generated summaries, paraphrases, or synthesized insights. Do NOT use it for actual quotes or excerpts copied directly from the text. The CLI injects `.generated` for discoverability and sets `location_type=none` since generated content has no source location. Generated highlights should still use the SAME (title, author, source_url) as verbatim highlights from the same source.
- **Highlight text**: supply `--text`, `--text-file`, or pipe content via stdin. The CLI refuses to guess. Bulk imports accept NDJSON rows with `text`, `title`, and `tags`.
- **Location best practices**: omit `--location` unless you can provide an absolute, client-agnostic reference (page number, character offset). When `--location` is omitted the payload leaves `location` blank so Readwise can reconcile it later. Valid `--location-type` values: `page` (books), `time_offset` (podcasts/videos), `order` (articles). For generated quotes the CLI defaults to `location_type=none`.
- **Dry runs**: add `--dry-run` to print the exact payload without calling the API. Dry-run output always shows the full payload (no field filtering).

## Scripts
- `${CLAUDE_PLUGIN_ROOT}/skills/readwise/scripts/readwise_client.py`: full-featured CLI covering highlight create/read/update, daily review, and books list/detail. Commands surface remaining rate-limit headers when provided so agents can throttle work.
- Shared helpers live in `${CLAUDE_PLUGIN_ROOT}/readwise_common/` (auth, HTTP retries, tag/location utilities); import from there when extending functionality to keep behavior consistent.

## Testing & validation
- Use the dry-run flag in the client to print payloads instead of sending them when iterating on workflows.
- Run `uv run --project ${CLAUDE_PLUGIN_ROOT} python -m compileall ${CLAUDE_PLUGIN_ROOT}/skills/readwise ${CLAUDE_PLUGIN_ROOT}/readwise_common` before shipping changes to catch syntax issues.
- For live smoke tests, set `READWISE_TOKEN` and exercise `--dry-run highlight create`, `highlights list`, and `highlights review` against a small limit to verify pagination + rate-limit logging.

## Source & license

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

- **Author:** [ryanlyn](https://github.com/ryanlyn)
- **Source:** [ryanlyn/readwise-skill](https://github.com/ryanlyn/readwise-skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ryanlyn-readwise-skill-readwise
- Seller: https://agentstack.voostack.com/s/ryanlyn
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.