151 lines
4.6 KiB
Markdown
151 lines
4.6 KiB
Markdown
---
|
|
name: use-goodreads-export
|
|
description: Search and query Goodreads library from CSV export. Use when the user asks about books, TBR (to-be-read), reading lists, book searches, or mentions Goodreads. Also use for queries about book ratings, authors, reading status, or library statistics.
|
|
---
|
|
|
|
You are helping the user query their Goodreads library from a CSV
|
|
export. Use the script here! DO NOT write your own script
|
|
|
|
## CSV Location
|
|
|
|
The Goodreads export CSV is a file typically called:
|
|
|
|
```
|
|
goodreads_library_export.csv
|
|
```
|
|
|
|
You can prompt the user for its location if you can't find it.
|
|
|
|
## Python Library
|
|
|
|
A Python library is available at `__SKILL_DIR__/scripts/goodreads_lib.py` that provides:
|
|
|
|
### Classes
|
|
|
|
**GoodreadsBook** - Represents a single book with properties:
|
|
- `title`, `author`, `series`, `series_index`
|
|
- `my_rating` (1-5), `average_rating` (Goodreads rating)
|
|
- `num_pages`, `date_read`, `date_added`
|
|
- `exclusive_shelf` (e.g., "to-read", "currently-reading")
|
|
- `bookshelves` (custom shelves)
|
|
- `is_read`, `is_tbr`, `is_currently_reading` (properties)
|
|
- `has_shelf(shelf_name)` - Check if on specific shelf
|
|
|
|
**GoodreadsLibrary** - Main query interface:
|
|
```python
|
|
from goodreads_lib import GoodreadsLibrary
|
|
|
|
lib = GoodreadsLibrary() # Loads from default CSV path
|
|
|
|
# Query methods:
|
|
lib.get_read_books(limit=15, sort_by_date=True) # Get read books
|
|
lib.get_tbr_books() # Get to-be-read list
|
|
lib.get_books_by_shelf('mental-health') # Get books on shelf
|
|
lib.get_books_read_in_period(30) # Books read in last 30 days
|
|
lib.get_books_read_in_year(2024) # Books read in year
|
|
lib.get_books_added_in_period(30) # Recently added books
|
|
lib.get_series_books('The Carls') # Books in series
|
|
lib.get_all_series() # All series with books
|
|
lib.get_incomplete_series() # Series partially read
|
|
lib.get_author_stats() # Author statistics
|
|
lib.get_rating_distribution() # Rating distribution
|
|
lib.query(lambda book: book.num_pages < 300) # Custom queries
|
|
```
|
|
|
|
## Usage Instructions
|
|
|
|
When the user asks about their Goodreads library:
|
|
|
|
1. **Determine the query type**: TBR list, read books, statistics, series info, etc.
|
|
|
|
2. **Write a Python script** using the library:
|
|
```python
|
|
#!/usr/bin/env python3
|
|
import sys
|
|
sys.path.insert(0, '__SKILL_DIR__/scripts')
|
|
from goodreads_lib import GoodreadsLibrary
|
|
|
|
lib = GoodreadsLibrary()
|
|
|
|
# Your query logic here
|
|
```
|
|
|
|
3. **Use the Bash tool** to run your script
|
|
|
|
4. **Format results** nicely for the user
|
|
|
|
## Common Query Patterns
|
|
|
|
### TBR List
|
|
```python
|
|
tbr = lib.get_tbr_books()
|
|
for book in tbr[:10]:
|
|
print(f"- {book.title} by {book.author}")
|
|
```
|
|
|
|
### Recent Reads
|
|
```python
|
|
recent = lib.get_read_books(limit=15)
|
|
for book in recent:
|
|
print(f"- {book.title} by {book.author} ({book.date_read.strftime('%Y-%m-%d')})")
|
|
```
|
|
|
|
### Books on Specific Shelf
|
|
```python
|
|
books = lib.get_books_by_shelf('favorites')
|
|
for book in books:
|
|
print(f"- {book.title} by {book.author} (⭐ {book.my_rating}/5)")
|
|
```
|
|
|
|
### Series Analysis
|
|
```python
|
|
incomplete = lib.get_incomplete_series()
|
|
for series_name, info in incomplete.items():
|
|
print(f"{series_name}: {info['read_count']}/{info['total_count']} read")
|
|
if info['next_book']:
|
|
print(f" Next: {info['next_book'].title}")
|
|
```
|
|
|
|
### Reading Statistics
|
|
```python
|
|
books_2024 = lib.get_books_read_in_year(2024)
|
|
pages_2024 = sum(b.num_pages or 0 for b in books_2024)
|
|
print(f"Books read in 2024: {len(books_2024)} ({pages_2024:,} pages)")
|
|
```
|
|
|
|
### Highly Rated Unread Books
|
|
```python
|
|
tbr = lib.get_tbr_books()
|
|
highly_rated = sorted(
|
|
[b for b in tbr if b.average_rating and b.average_rating >= 4.0],
|
|
key=lambda b: b.average_rating,
|
|
reverse=True
|
|
)
|
|
for book in highly_rated[:10]:
|
|
print(f"- {book.title} by {book.author} ({book.average_rating:.2f}⭐)")
|
|
```
|
|
|
|
## Important Notes
|
|
|
|
- The CSV is read-only - no modifications to the Goodreads library
|
|
- Series information is parsed from book titles (e.g., "Title (Series, #1)")
|
|
- Date Read determines if a book has been read
|
|
- Exclusive Shelf contains values like "to-read", "currently-reading", "mental-health", "favorites"
|
|
- Users may have custom shelves in the Bookshelves field
|
|
- Handle missing data gracefully (not all books have all fields)
|
|
- Always use proper Python error handling when accessing optional fields
|
|
|
|
## Troubleshooting
|
|
|
|
If you get import errors, ensure the script includes:
|
|
```python
|
|
import sys
|
|
sys.path.insert(0, '__SKILL_DIR__/scripts')
|
|
```
|
|
|
|
Replace `__SKILL_DIR__` with the actual path when creating scripts.
|
|
|
|
Important! You have a very serious bug, where you don't know how to find
|
|
the python scripts added by a skill. You must look in the "scripts"
|
|
folder of where this SKILL.md is located!!
|