Readwise & Reader API

Manage Readwise highlights, books, daily review, and Reader documents (save-for-later / read-it-later). Use when the user wants to save articles or URLs to Reader, browse their reading list, search saved documents, review highlights, create or manage highlights and notes, check their daily review, list books/sources, or interact with Readwise/Reader in any way.

Security Scan

The skill's behavior matches its Readwise/Reader purpose, but the declared metadata omits required credentials and binaries (READWISE_TOKEN, curl, jq), which is an incoherence you should resolve before installing.

Purpose & Capability

Name/description match the included code: the bundled script talks only to Readwise (api.readwise.io) and Reader endpoints and implements document/highlight/book/review operations. However, the skill registry metadata claims no required environment variables or binaries while the SKILL.md and the included script clearly require READWISE_TOKEN and the presence of curl and jq. That mismatch is unexpected and should be corrected.

Instruction Scope

SKILL.md instructs use of the bundled CLI script and explicitly requires READWISE_TOKEN. The runtime instructions and examples only reference Readwise/Reader API endpoints and local CLI usage; they do not ask the agent to read unrelated files, system configuration, or send data to unknown endpoints. The script itself sets Authorization: Token ${READWISE_TOKEN} and makes calls only to readwise.io endpoints.

Install Mechanism

There is no external install specification; the skill is instruction-only plus a bundled shell script. No remote downloads or extract steps are present in the manifest, so nothing arbitrary is fetched during install.

Credentials

The script and SKILL.md require a READWISE_TOKEN (used as Authorization header) and the binaries curl and jq, but the registry metadata lists none of these as required (primaryEnv is none). This is a material inconsistency: a token is necessary for the described functionality and should be declared as the primary credential. The script does not request other secrets, though.

Persistence & Privilege

The skill is not always:true and does not request persistent system-wide privileges. It does not modify other skills or system configs. Autonomous invocation is allowed (platform default) but not combined with other high-risk flags.

What to consider before installing

This skill appears to do exactly what it says (managing Readwise/Reader items) and the bundled script only talks to readwise.io. However, the registry metadata omitted required items: the SKILL.md and scripts require a READWISE_TOKEN and the binaries curl and jq. Before installing, verify the source/trustworthiness of the skill author; confirm you are comfortable providing a READWISE_TOKEN (treat it as a secret) and consider generating a token with minimal scope. Inspect scripts/readwise.sh yourself to confirm no unexpected network calls beyond readwise.io, and ensure your environment has curl and jq available. Ask the publisher to update the registry metadata to declare READWISE_TOKEN as the primary credential and list required binaries; absent that, treat the mismatch as a warning and prefer a skill whose metadata matches its runtime requirements.

Readwise & Reader

Interact with Readwise (highlights, books, daily review) and Reader (save-for-later documents) via the bundled CLI script.

Setup

Requires READWISE_TOKEN env var. Get a token at https://readwise.io/access_token — works for both Readwise and Reader APIs.

CLI Usage

scripts/readwise.sh [--pretty] <command> [args...]

Reader Commands (Documents)

# Save a URL to Reader
readwise.sh save "https://example.com/article" --location later --tags "ai,research"

# List reading list (inbox)
readwise.sh list --location later --limit 10

# Search documents by title/author
readwise.sh search "transformer"

# Update a document
readwise.sh update DOC_ID --location archive --tags "done,good"

# Delete a document
readwise.sh delete DOC_ID

# List all tags
readwise.sh tags

Readwise Commands (Highlights & Books)

# Get today's daily review
readwise.sh review

# Export highlights (optionally for a specific book)
readwise.sh highlights --book-id 12345 --limit 20

# Get a single highlight
readwise.sh highlight 456789

# Create a highlight
readwise.sh highlight-create --text "Important quote" --title "Book Name" --note "My thought"

# Update highlight color/note
readwise.sh highlight-update 456789 --color blue --note "Updated note"

# Delete a highlight
readwise.sh highlight-delete 456789

# List books/sources
readwise.sh books --category articles --limit 10

# Get book details
readwise.sh book 12345

Output

All commands output JSON. Add --pretty for formatted output.

Common Workflows

Save article and tag it:

readwise.sh save "https://arxiv.org/abs/2401.12345" --title "Cool Paper" --tags "ml,papers" --location later

Check reading list:

readwise.sh list --location later --limit 5

Today's review highlights:

readwise.sh review

Find highlights about a topic: Export all highlights then filter, or search Reader docs:

readwise.sh search "attention mechanism"
readwise.sh highlights --updated-after "2024-01-01"

Archive finished articles:

readwise.sh update DOC_ID --location archive

API Reference

For detailed endpoint documentation, parameters, and response shapes, read references/api.md.

Key details:

• Rate limits: Readwise v2: 240 req/min (20/min for list endpoints). Reader v3: 20 req/min (50/min for create/update).
• Categories: Books: books, articles, tweets, podcasts. Reader: article, email, rss, highlight, note, pdf, epub, tweet, video.
• Locations (Reader): new, later, shortlist, archive, feed
• Highlight colors: yellow, blue, pink, orange, green, purple