| 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 notebookscripts/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.
