Agent skill

readwise

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.

View SKILL.md on GitHub Repository
Stars 6
Forks 1

Install this agent skill to your Project

npx add-skill https://github.com/edwinhu/workflows/tree/main/skills/readwise

SKILL.md

Readwise

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="workflows:librarian", prompt="Search Readwise for proxy advisor articles and summarize findings")

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

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)

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

edwinhu/workflows

audit-fix-loop

This skill should be used when the user asks to 'iteratively improve', 'audit and fix', 'hill-climb quality', 'grade and improve', 'score and fix', 'audit loop', 'quality loop', or needs structured iterative improvement of an artifact using scored independent audits. Also use when the user invokes a ralph loop for quality improvement rather than task completion.

6 1
Explore
edwinhu/workflows

ds-spec-reviewer

Internal skill used by ds-brainstorm at Phase 1 exit gate. Dispatches a reviewer subagent to verify SPEC.md completeness before planning. NOT user-facing.

6 1
Explore
edwinhu/workflows

pptx-render

Use when the user asks to "render pptx", "show pptx slide", "compare with pptx", "pptx to image", "export pptx slide", "original slide", "show me the original", "what does the pptx look like", or needs to extract a specific PPTX slide's content for visual comparison.

6 1
Explore
edwinhu/workflows

obsidian-organize

Organize Obsidian notes according to clawd's preferences. Use when user asks to "organize notes", "move notes to right folder", "clean up vault", "tidy vault", "file this note", or when creating new notes in the Obsidian vault. Also use when moving, renaming, or categorizing notes, or when the vault root has stray files.

6 1
Explore
edwinhu/workflows

dev-verify

This skill should be used when the user asks to 'verify completion', 'check that tests pass', 'confirm feature works', or REQUIRED Phase 7 of /dev workflow (final). Enforces fresh runtime evidence before claiming completion.

6 1
Explore
edwinhu/workflows

dev

This skill should be used when the user asks to 'start a feature', 'build a feature', 'implement a feature', 'develop', 'new feature', or needs the full 7-phase development workflow with TDD enforcement.

6 1
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results