| name | readwise-skill |
| description | Import books, articles, podcasts, and other content from Readwise into Content Notes with all highlights and annotations. Use when user wants to import specific content from their Readwise library. |
| version | 1.0.0 |
| dependencies | ["python3","requests","python-dotenv"] |
| allowed-tools | ["Bash","Read","Write"] |
Readwise Import Skill
Overview
This skill imports books, articles, podcasts, and other content from your Readwise library into Content Notes as source documents. It fetches all highlights, annotations, and metadata, creating a properly formatted markdown document that can be analyzed later.
When to Apply
Use this skill when:
- User wants to only import without analysis (rare)
- User explicitly says "just import" or "import only"
- User wants to sync/update existing Readwise imports with new highlights
- User asks to search their Readwise library without importing
IMPORTANT: Most users want to analyze content after importing. If user says:
- "analyze [item] from Readwise"
- "generate insights from [item]"
- "what themes are in [item]?"
Use readwise-content-analyzer skill instead - it will handle BOTH import and analysis automatically.
Do NOT use this skill for:
- Bulk importing entire Readwise library (use on-demand only)
- Reading Readwise content without importing to Content Notes
- Managing Readwise account settings
- Analysis requests (use readwise-content-analyzer instead)
Inputs
- Item identifier - Either:
- Item title/name (e.g., "Atomic Habits", "The Mom Test")
- Author name (e.g., "Tim Urban", "Rob Fitzpatrick")
- Readwise book ID (if known)
- Action - import (new) or sync (update existing)
Outputs
- Source document in
/sources/ directory
- Filename format:
YYYY-MM-DD_Author_Title_Readwise.md
- Includes: metadata, all highlights in chronological order, annotations, tags
- Git commit (automatic)
- Summary of what was imported
Setup Instructions
First Time Setup
-
Get Readwise API Token:
-
Configure Credentials:
echo "READWISE_API_TOKEN=your_token_here" > ~/.claude/secrets/readwise/.env
-
Install Dependencies:
cd ~/.claude/skills/readwise-skill
pip3 install -r requirements.txt
-
Test Authentication:
cd ~/.claude/skills/readwise-skill/scripts
python3 auth.py
Instructions for Claude
Step 1: Validate Setup
Step 2: Search for Content
If user provides a title or author name (not book ID):
cd ~/.claude/skills/readwise-skill/scripts
python3 search.py --query "atomic habits"
For specific categories:
python3 search.py --query "tim urban" --category articles
Show results to user and ask which one to import.
Step 3: Import Content
Once you have the book ID:
cd ~/.claude/skills/readwise-skill/scripts
python3 import_item.py --book-id 12345 --output-dir "/Users/jvincent/Projects/Knowledge System/notes/content notes/sources"
The script outputs JSON with:
{
"success": true,
"filename": "2026-02-10_James-Clear_Atomic-Habits_Readwise.md",
"filepath": "/full/path/to/file.md",
"title": "Atomic Habits",
"author": "James Clear",
"category": "books",
"num_highlights": 47,
"book_id": "12345"
}
Step 4: Report Results
Tell the user:
- ✅ Successfully imported [Title] by [Author]
- 📝 [N] highlights imported
- 📂 Saved to:
sources/[filename]
- 🔗 Book ID: [id] (for future syncing)
Step 5: Auto-Commit to Git
After successful import, automatically commit to git:
cd "/Users/jvincent/Projects/Knowledge System/notes/content notes"
git add .
git commit -m "Add Readwise import: [Title] by [Author]
Imported [N] highlights from Readwise
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>"
git push
Step 6: Suggest Next Steps
After import, ask:
- "Would you like me to analyze this content and generate insights?"
- This leads to the
readwise-content-analyzer skill
Syncing Updates
To update an existing import with new highlights:
cd ~/.claude/skills/readwise-skill/scripts
python3 sync.py --filepath "/Users/jvincent/Projects/Knowledge System/notes/content notes/sources/2026-02-10_James-Clear_Atomic-Habits_Readwise.md"
The script:
- Extracts book ID from the existing file
- Fetches latest highlights from Readwise
- Regenerates the entire document with all highlights
- Reports how many new highlights were added
After syncing, commit the changes to git.
Output Format
Generated source documents have this structure:
# [Title] | [Author] - Readwise
## Metadata
- **Type**: Book / Article / Podcast / etc.
- **Author**: [Author name]
- **Source URL**: [URL if available]
- **Date Imported**: YYYY-MM-DD
- **Total Highlights**: [count]
- **Readwise Tags**: #tag1, #tag2
## Document Notes
[Your document-level notes from Readwise]
## Your Highlights
### Highlight 1 (Page 15)
> "The highlighted text goes here"
**Your Note**: Your annotation from Readwise
**Tags**: #important, #actionable
---
### Highlight 2 (Position 234)
> "Another highlight"
---
[... all highlights in chronological order ...]
## Synthesis Analysis
_To be completed during analysis phase_
## Key Themes Identified
_To be completed during analysis phase_
## Related Synthesis Documents
_Add connections to existing themes:_
- [[Theme 1]]
- [[Theme 2]]
## Source Information
- **Readwise Book ID**: 12345
- **Category**: books
- **Original URL**: https://...
Error Handling
Common errors:
- "READWISE_API_TOKEN not found": Run setup instructions
- "Authentication failed": Token is invalid, regenerate at readwise.io/access_token
- "No results found": Try different search terms or check category
- "No highlights found": Item exists but has no highlights
- Rate limit exceeded: Wait and retry (API limits: 240/min general, 20/min for list endpoints)
Examples
Example 1: Import a Book
User: "Import 'The Mom Test' from Readwise"
Claude:
- Searches:
python3 search.py --query "the mom test"
- Shows results:
Found 1 result(s):
1. [BOOKS] The Mom Test
Author: Rob Fitzpatrick
Highlights: 23
ID: 12345
- Confirms with user
- Imports:
python3 import_item.py --book-id 12345 --output-dir ".../sources"
- Reports: "✅ Imported The Mom Test by Rob Fitzpatrick with 23 highlights"
- Commits to git
- Asks: "Would you like me to analyze this content?"
Example 2: Import an Article
User: "Import that Tim Urban article about AI"
Claude:
- Searches:
python3 search.py --query "tim urban" --category articles
- Shows multiple results, user picks one
- Imports the article
- Commits to git
Example 3: Sync Updates
User: "Sync my Atomic Habits import with new highlights"
Claude:
- Finds existing file:
sources/2026-02-10_James-Clear_Atomic-Habits_Readwise.md
- Syncs:
python3 sync.py --filepath "..."
- Reports: "Updated: 3 new highlights (47 → 50)"
- Commits changes to git
Example 4: Search and Browse
User: "What articles do I have from Y Combinator in Readwise?"
Claude:
- Searches:
python3 search.py --query "y combinator" --category articles
- Lists all matches
- Asks if user wants to import any
Related Skills
This skill is part of the Readwise → Analysis workflow:
┌─────────────────────┐
│ readwise-skill │ ← YOU ARE HERE
│ (import content) │
└──────────┬──────────┘
│
▼
┌──────────────────────────────┐
│ readwise-content-analyzer │ → Analyze highlights + content
│ (generate insights) │ Generate synthesis documents
└──────────────────────────────┘
Next steps after import:
- Use
readwise-content-analyzer to analyze the highlights
- Generate/update synthesis documents
- Connect to existing themes
Testing Checklist
API Rate Limits
- General endpoints: 240 requests/minute
- List endpoints (books, highlights): 20 requests/minute
- Scripts handle rate limits automatically
- Large imports may take several minutes
Security
- API Token: Stored in
~/.claude/secrets/readwise/.env (gitignored)
- Never log or display token
- If token compromised, regenerate at readwise.io/access_token
- Source documents may contain personal notes/highlights
- Always commit to private repository
Readwise API Reference
