How do I install the Readwise Search skill?

Run npx skillmds@latest add edwinhu/readwise-search in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Readwise Search safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Readwise Search?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Readwise Search free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Readwise Search?

edwinhu (@edwinhu) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Readwise Search by edwinhu — Agent Skill

Name: Readwise Search
Author: edwinhu

Readwise Search

ALWAYS use when the user wants something out of their own reading library — "what did I highlight about X", "search my highlights", "find in readwise", "my notes on X", "did I save anything on Y", "what have I read about Z", "find that quote I saved", "pull quotes from my reading", "who was it that said X". Use proactively before answering from memory whenever the user refers to their own reading or annotations. NOT for conversational summarizing across highlights (readwise-chat), listing or saving Reader documents (readwise-docs), or cleanup (readwise-prune).

edwinhu 9afe737 3.5 KB Updated Sep 17, 2026

File contents

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

---name: readwise-searchdescription: ALWAYS use when the user wants something out of their own reading library — "what did I highlight about X", "search my highlights", "find in readwise", "my notes on X", "did I save anything on Y", "what have I read about Z", "find that quote I saved", "pull quotes from my reading", "who was it that said X". Use proactively before answering from memory whenever the user refers to their own reading or annotations. NOT for conversational summarizing across highlights (readwise-chat), listing or saving Reader documents (readwise-docs), or cleanup (readwise-prune).---# 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```bash# Semantic searchreadwise readwise-search-highlights --vector-search-term "fiduciary duty broker-dealer"# With fulltext filtersreadwise readwise-search-highlights --vector-search-term "regulation" \ --full-text-queries '[{"field_name": "document_author", "search_term": "Jackson"}]'# JSON output for pipingreadwise 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```bash# Hybrid search across document contentreadwise reader-search-documents --query "proxy advisors"# With filtersreadwise reader-search-documents --query "regulation" --author-search "Jackson" --category-in articlereadwise 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 locationreadwise reader-list-documents --category article --location archive# Recent updatesreadwise reader-list-documents --updated-after 2026-01-01T00:00:00Z --limit 20```### Keyword Highlight Search — Custom CLI```bash# 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 FormatUse `--json` for structured output. JSON search results include a `score` field (higher = more relevant, >0.01 typically meaningful).

Frequently asked questions