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.