Readwise

## IRON LAW: Main Chat NEVER Calls Readwise Tools or CLI

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

Main chat MUST NOT:

• Call mcp__readwise__search_readwise_highlights directly
• Call any mcp__readwise__* tool
• Run readwise 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 MCP Tools
Main chat	FORBIDDEN	FORBIDDEN
Librarian sub-agent	ALLOWED	NOT NEEDED (CLI replaces MCP)

Red Flag Detection

STOP if you catch yourself thinking:
- "Let me quickly search Readwise..."
- "I'll just run readwise search..."
- "The MCP tool is right here in my tool list..."

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")

NEVER IN MAIN CHAT:
readwise search "proxy advisors"
mcp__readwise__search_readwise_highlights(...)

---

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 list│ ← For tagged items
    │    --tag "X"        │
    │    NOT search!      │
    └─────────────────────┘

---

Readwise CLI Quick Reference

The readwise CLI (~/.local/bin/readwise) covers all Readwise API surfaces.

Need	Command
Semantic search highlights	readwise search "query"
Documents by tag	readwise list --tag "X"
Full document content	readwise get <id> --html
RAG chat over highlights	readwise chat "question"
Keyword search highlights	readwise highlights --search "term"
List all tags	readwise tags
Prune stale docs	readwise prune

Sub-skills with detailed reference:

Skill	Purpose
readwise-search	Vector + fulltext highlight search
readwise-docs	Document CRUD (list, get, save, update, delete)
readwise-chat	GPT-5.1 RAG chat over highlights
readwise-prune	Two-pass stale document cleanup

---

Batch Add to NLM (by tag)

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 get <id> --html.

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