readwise-search - SKILL.md Agent Skill

name: readwise-search description: Search Readwise highlights. Use when the user wants to find highlights, quotes, notes, or annotations from their reading library. Triggers on "search highlights", "find in readwise", "what did I highlight about", "my notes on". context: fork agent: librarian user-invocable: false

Readwise Highlight Search

Decision Tree

1. Do you know the EXACT document or author?
   YES -> Use fulltext filters (--full-text-queries)
   NO  -> Use vector search (semantic query)
2. Need document-level results (not highlights)?
   YES -> Use `readwise reader-search-documents --query "term"`
          or `readwise reader-list-documents` with --tag or --category filters
   NO  -> Use `readwise readwise-search-highlights`
3. Need keyword-exact match in highlight text?
   YES -> Use `readwise-custom highlights --search "term"` (v2 API)
   NO  -> Use vector search

Quick Reference

Vector + Fulltext Search (Highlights) — Official CLI

# Semantic search
readwise readwise-search-highlights --vector-search-term "fiduciary duty broker-dealer"

# With fulltext filters
readwise readwise-search-highlights --vector-search-term "regulation" \
  --full-text-queries '[{"field_name": "document_author", "search_term": "Jackson"}]'

# JSON output for piping
readwise readwise-search-highlights --vector-search-term "query" --json

Fulltext filter fields (via --full-text-queries JSON array):

field_name	Searches
`document_author`	Document author name
`document_title`	Document title
`highlight_note`	Highlight notes/annotations
`highlight_plaintext`	Highlight text content
`highlight_tags`	Tags on highlights

Document Search (Hybrid) — Official CLI

# Hybrid search across document content
readwise reader-search-documents --query "proxy advisors"

# With filters
readwise reader-search-documents --query "regulation" --author-search "Jackson" --category-in article
readwise reader-search-documents --query "proxy" --tags-in "corps" --location-in later,archive

# By tag (no search, just filter)
readwise reader-list-documents --tag "proxy advisors" --json

# By category and location
readwise reader-list-documents --category article --location archive

# Recent updates
readwise reader-list-documents --updated-after 2026-01-01T00:00:00Z --limit 20

Keyword Highlight Search — Custom CLI

# Exact text search across highlights (v2 API)
readwise-custom highlights --search "fiduciary" --limit 20 --json

When to Use Each

Need	Command	CLI
Semantic/conceptual highlight search	`readwise readwise-search-highlights --vector-search-term "query"`	Official
Hybrid document content search	`readwise reader-search-documents --query "term"`	Official
Keyword-exact match in highlights	`readwise-custom highlights --search "term"`	Custom
Documents by tag	`readwise reader-list-documents --tag "X"`	Official
Specific document	`readwise reader-get-document-details --document-id <id>`	Official

Output Format

Use --json for structured output. JSON search results include a score field (higher = more relevant, >0.01 typically meaningful).