readwise

Readwise

What this skill carries — grep references/ for any subject the names below miss: !d=${CLAUDE_SKILL_DIR}; command -v skill-toc >/dev/null 2>&1 && exec skill-toc "$d"; s=$HOME/.claude/skills/plugin-utils/bin/skill-toc; [ -x "$s" ] && exec "$s" "$d"; echo "(skill-toc unavailable: references and scripts are NOT listed here — install the plugin-utils plugin, or start a new session so its bin/ reaches PATH)"

EVERY READWISE OPERATION MUST GO THROUGH LIBRARIAN. This is not negotiable.

Main chat MUST NOT:

Run readwise CLI commands directly
Run readwise-custom CLI commands directly
"Just quickly check" highlights

If you're about to do anything Readwise in main chat, STOP. Spawn a librarian sub-agent instead.

Permission Model

Context	Readwise CLI	readwise-custom CLI
Main chat	FORBIDDEN	FORBIDDEN
Librarian sub-agent	ALLOWED	ALLOWED

Red Flag Detection

STOP if you catch yourself thinking:
- "Let me quickly search Readwise..."
- "I'll just run readwise reader-search-documents..."
- "I'll just run readwise-custom search..."

These thoughts in MAIN CHAT = VIOLATION. Delegate instead.

Correct Pattern

User: "Search my Readwise for proxy advisor articles"

MAIN CHAT RESPONSE:
Task(subagent_type="librarian", prompt="Search Readwise for proxy advisor articles and summarize findings", run_in_background=false)
# Blocking: the answer to the user IS the agent's result, so dispatch synchronously.

NEVER IN MAIN CHAT:
readwise readwise-search-highlights --vector-search-term "proxy advisors"
readwise-custom search "proxy advisors"

Two CLIs

CLI	Binary	Use for
Official (`@readwise/cli`)	`readwise`	Search, list, get, save, move, tags, highlights CRUD, export, daily review
Custom (`~/projects/readwise-cli/`)	`readwise-custom`	Chat/RAG, ghostreader, file upload (PDF/EPUB), prune, keyword highlight search

Tag-Based Workflow

Trigger Phrases

"we added items tagged X"
"I thought we added X to NLM"
"items tagged [tag]"
"documents with tag [tag]"

Required Workflow

User mentions tagged items or NLM content
              │
              ▼
    ┌──────────────────────────────────┐
    │ 1. CHECK NLM FIRST              │ ← MANDATORY
    │    nlm list                     │
    │    nlm chat <id>                │
    └──────────────────────────────────┘
              │
       Not in NLM?
              ▼
    ┌──────────────────────────────────┐
    │ 2. USE readwise for tagged items │
    │    readwise reader-list-documents│
    │    --tag "X"                     │
    │    NOT search!                   │
    └──────────────────────────────────┘

Quick Reference

Official CLI (`readwise`)

Need	Command
Semantic search highlights	`readwise readwise-search-highlights --vector-search-term "query"`
Search documents (hybrid)	`readwise reader-search-documents --query "query"`
Documents by tag	`readwise reader-list-documents --tag "X"`
Full document (markdown)	`readwise reader-get-document-details --document-id <id>`
List all tags	`readwise reader-list-tags`
Save URL	`readwise reader-create-document --url <url>`
Move documents	`readwise reader-move-documents --document-ids <id> --location archive`
Bulk edit metadata	`readwise reader-bulk-edit-document-metadata --documents '[...]'`
Export library	`readwise reader-export-documents`
Daily review	`readwise readwise-get-daily-review`

Add --json to any command for machine-readable output.

Custom CLI (`readwise-custom`)

Need	Command
RAG chat over highlights	`readwise-custom chat "question"`
Keyword search highlights	`readwise-custom highlights --search "term"`
Prune stale docs	`readwise-custom prune`
Upload PDF/EPUB	`readwise-custom upload <file>`
Ghostreader	`readwise-custom ghostread summarize <id>`
Full document (HTML)	`readwise-custom get <id> --html`

Sub-skills with detailed reference:

Skill	Purpose
`readwise-search`	Vector + fulltext highlight search
`readwise-docs`	Document CRUD (list, get, save, move, bulk edit, export)
`readwise-chat`	GPT-5.1 RAG chat over highlights (fallback — prefer search + Claude synthesis)
`readwise-prune`	Two-pass stale document cleanup

Batch Add to NLM (by tag)

uv run python3 "${CLAUDE_SKILL_DIR}"/scripts/readwise_to_nlm.py \
  --tag "proxy advisors" --tag "disclosure" \
  --notebook <notebook-id>

Add --dry-run to preview. Add --verbose for detailed output.

Anti-Pattern: Never Fetch from Source URL

WRONG: Search Readwise, find document, fetch from original URL (fails for paywalled content).

RIGHT: Search Readwise, get full text FROM READWISE using readwise reader-get-document-details --document-id <id>.

If a document is in Readwise, the full text is already there. Never go back to the source URL.

Additional Resources

Reference Files

references/reader-api.md - Reader API reference (endpoints, pagination, updatedAfter semantics, document fields) for cases the CLI doesn't cover

Scripts

scripts/readwise_to_nlm.py - Export Readwise documents into a NotebookLM notebook
scripts/readwise_prune.py - Direct-API pruning implementation. The sanctioned path is readwise-custom prune (see /readwise-prune), which exposes the same flags; keep this only for API-level work the CLI doesn't expose.