analyze-goodreads-export

name	analyze-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:

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:

   #!/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

tbr = lib.get_tbr_books()
for book in tbr[:10]:
    print(f"- {book.title} by {book.author}")

Recent Reads

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

books = lib.get_books_by_shelf('favorites')
for book in books:
    print(f"- {book.title} by {book.author} (⭐ {book.my_rating}/5)")

Series Analysis

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

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

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
• Use .get() with defaults for optional fields; skip a book only when a required field is absent
• Always use proper Python error handling when accessing optional fields

Troubleshooting

If you get import errors, ensure the script includes:

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!!