readwise

name	readwise
description	This skill should be used when the user asks to "search Readwise", "find highlights", "get quotes from my reading", "add highlights to notebook", "search my annotations", "get full document text", "fetch article content", "add tagged documents to notebook", or needs to query their Readwise library.
version	1.0.0
context	fork
agent	librarian
user-invocable	false

Readwise

## IRON LAW: Main Chat NEVER Calls Readwise CLI

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="workflows: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

**When user mentions items were added by tag, NEVER use semantic search.**

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 /Users/vwh7mb/projects/workflows/skills/readwise/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.