Readwise

---
name: readwise
description: 'ALWAYS use for ANY query against the user''s own reading library — "search Readwise", "find highlights", "what did I highlight about X", "get quotes from my reading", "search my annotations", "find that thing I saved about Y", "pull the full text of that article", "what do my notes say on this", "add my highlights to a notebook", "add tagged documents to notebook". Use even when the user never says "Readwise" but is asking about something they read or saved. NOT for web or academic search — this searches only their curated library.'
version: 1.0.0
context: fork
agent: librarian
user-invocable: false
---

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

<EXTREMELY-IMPORTANT>
## 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.**
</EXTREMELY-IMPORTANT>

### 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

<EXTREMELY-IMPORTANT>
**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!                   │
    └──────────────────────────────────┘
```
</EXTREMELY-IMPORTANT>

---

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

```bash
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.