功能描述

Full Goodreads integration: read shelves, search books, get details/reviews via RSS, and write actions (rate, shelf, review, edit dates, progress) via Playwr...

使用说明 (SKILL.md)

Goodreads Skill

Name: Goodreads (Read + Write)
Author: phuc-nt

Full read + write access to Goodreads via RSS feeds and Playwright browser automation.

Scripts

# Read-only (RSS + scraping, no login required)
R=scripts/goodreads-rss.py

# Write (Playwright browser automation, requires one-time login)
W=scripts/goodreads-write.sh

Setup

See references/SETUP.md for installation and first-time login instructions.

Quick start:

# Install dependencies
pip install playwright playwright-stealth
playwright install chromium

# Login to Goodreads (one-time, opens browser)
./scripts/goodreads-write.sh login

User Configuration

Replace \x3CUSER_ID> with your Goodreads user ID in all commands below.

How to find your user ID: Go to your Goodreads profile page. The URL will be like: goodreads.com/user/show/12345678-yourname — the number is your user ID.

For write commands with RSS verification, set:

export GOODREADS_USER_ID="\x3CYOUR_USER_ID>"

Read Commands

1. View shelf

python3 $R shelf \x3CUSER_ID> --shelf \x3Cshelf> [--limit N] [--sort \x3Csort>]

`--shelf`	Meaning
`currently-reading`	Currently reading
`read`	Already read
`to-read`	Want to read
`\x3Ccustom>`	Custom shelf

`--sort`	Meaning
`date_read`	Date finished (default for `read`)
`date_added`	Date added to shelf
`rating`	Personal rating
`title`	Book title
`author`	Author name
`avg_rating`	Average Goodreads rating

Examples:

python3 $R shelf \x3CUSER_ID> --shelf currently-reading
python3 $R shelf \x3CUSER_ID> --shelf read --limit 20 --sort date_read
python3 $R shelf \x3CUSER_ID> --shelf to-read --limit 50
python3 $R shelf \x3CUSER_ID> --shelf read --limit 200 --sort rating

Fields returned: title, author, book_id, isbn, user_rating (0–5), average_rating, date_read, date_added, review, shelves, description (300 chars), published, book_url

2. Recent activity

python3 $R activity \x3CUSER_ID> [--limit N]

Returns: books added, marked read, reviews written...

3. Search books

python3 $R search "\x3Cquery>" [--limit N]

python3 $R search "Jared Diamond" --limit 10
python3 $R search "atomic habits" --limit 5

Returns: book_id, title, author, book_url

4. Book details

python3 $R book \x3Cbook_id>

Returns: title, author, average_rating, rating_count, review_count, description, isbn, published, genres, image_url

5. Book reviews

python3 $R reviews \x3Cbook_id> [--limit N]

⚠️ Reviews are rendered via React — available count may be limited.

Write Commands

Requires one-time login. Run $W login first. Session persists for weeks/months.

1. Check login status

$W status

2. Rate a book

$W rate \x3Cbook_id> \x3Cstars>

Stars: 1–5 (integer)

$W rate 40121378 5        # Rate Atomic Habits 5 stars

3. Change shelf

$W shelf \x3Cbook_id> \x3Cshelf_name>

`shelf_name`	Display	Notes
`to-read`	Want to Read
`currently-reading`	Currently Reading
`read`	Read

Output includes "verified": true/false — RSS auto-confirms after action.

$W shelf 186190 read                # Move to "Read"
$W shelf 186190 currently-reading   # Move to "Currently Reading"

4. Start reading

$W start \x3Cbook_id>

Shortcut for shelf \x3Cbook_id> currently-reading. RSS verified.

5. Finish reading

$W finish \x3Cbook_id>

Shortcut for shelf \x3Cbook_id> read. RSS verified.

6. Edit (dates, review, rating)

$W edit \x3Cbook_id> [--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] [--stars N] [--review "text"]

Uses the /review/edit/ page — can edit everything in one command.

⚠️ Book must be shelved first (use $W shelf or $W start).

Examples:

$W edit 186190 --start-date 2025-01-15 --end-date 2025-02-20
$W edit 186190 --stars 4
$W edit 186190 --review "Great book, highly recommend."
$W edit 186190 --start-date 2025-03-01 --end-date 2025-03-08 --stars 4 --review "Updated review"

7. Write/Update review

$W review \x3Cbook_id> "\x3Ctext>"

8. Update reading progress

$W progress \x3Cbook_id> \x3Cpage_or_percent>

⚠️ Book must be on currently-reading shelf.

$W progress 13618551 150    # Reading page 150

Sample Workflows

"What am I currently reading?"

python3 $R shelf \x3CUSER_ID> --shelf currently-reading

"Find books about Japanese history"

python3 $R search "Japanese history" --limit 10
# → get book_id → python3 $R book \x3Cid> for details

"I just finished Forrest Gump, rate 4 stars, read from 3/1 to 3/8"

$W finish 186190
$W edit 186190 --stars 4 --start-date 2025-03-01 --end-date 2025-03-08

"Start reading Atomic Habits"

$W start 40121378

Output Format

All commands return JSON:

{
  "success": true,
  "action": "edit",
  "book_id": "186190",
  "changes": ["start_date=2025-03-01", "end_date=2025-03-08", "stars=4"],
  "message": "Updated: start_date=2025-03-01, end_date=2025-03-08, stars=4"
}

Limitations

Feature	Status
Read shelf	✅ RSS, max 200 books/request
Activity feed	✅ RSS
Search books	✅ Scraping
Book details	✅ Scraping + JSON-LD
Reviews	⚠️ Limited scraping
Rate (1-5 stars)	✅
Change shelf (+ RSS verify)	✅
Start/Finish reading	✅
Write/edit review	✅
Edit reading dates	✅
Update progress	✅ (requires currently-reading)
Session persistence	✅ (stealth, weeks/months)
Remove from shelf	❌ Not supported
Custom shelves (write)	❌ Only 3 main shelves

Note: Goodreads may change its UI → scripts may break. If errors occur, check selectors. Anti-bot: Uses playwright-stealth + --disable-blink-features=AutomationControlled.

安全使用建议

This skill appears to do what it says: read Goodreads via RSS/scraping and perform writes by automating a browser. Before installing: (1) review the scripts yourself if you can (they are included); (2) run the tool inside a dedicated virtual environment as instructed (do not install playwright globally unless you want that); (3) be aware the one-time login will store cookies in scripts/.browser-data so the tool can act later without re-authenticating — if you don't want long-lived access, use a throwaway Goodreads account or remove the .browser-data directory and revoke sessions in your Goodreads/Amazon account after use; (4) remember that if you allow the agent to call skills autonomously, it could perform write actions using the saved session — lock down autonomous execution or require manual invocation for write operations if that concerns you.

功能分析

Type: OpenClaw Skill Name: goodreads-full Version: 1.0.0 The Goodreads skill bundle provides legitimate functionality for reading and writing data to Goodreads using RSS feeds and Playwright browser automation. The implementation uses a secure manual login process for authentication, storing session cookies locally in a persistent browser context rather than handling user credentials directly. No evidence of data exfiltration, malicious execution, or prompt injection was found; all network activity is directed to official Goodreads endpoints (goodreads.com).

能力评估

✓ Purpose & Capability

Name/description promise read+write Goodreads functionality. The package only requires python3 and Playwright (used for browser automation) and includes RSS scraping code for read-only functionality — these map to the stated purpose. The few path references (scripts/.venv vs a stray reference to ~/.openclaw/common-scripts/.venv in a docstring) are minor documentation inconsistencies, not indications of unrelated capabilities.

ℹ Instruction Scope

SKILL.md and scripts instruct the agent/user to install playwright and playwright-stealth, run a one-time interactive browser login, and then perform headless automated actions. Read commands use Goodreads RSS and page scraping only. There are no instructions to read arbitrary local files or to contact any third-party endpoints beyond Goodreads. Note: the skill instructs storing persistent browser data (cookies) locally to maintain sessions; that enables later write operations without re-login.

✓ Install Mechanism

There is no automated install spec in the registry — installation is manual via pip (pip install playwright playwright-stealth) and playwright install chromium as documented. This is a common/expected approach for Playwright-based tools; it is not an opaque remote download from a personal server. Risk is standard for pip-installed packages (supply-chain risk) but proportionate to the functionality.

✓ Credentials

The skill does not declare or require secrets/credentials from the environment. It optionally recommends setting GOODREADS_USER_ID for RSS verification and supports a GR_VENV env var to override the venv location — both are appropriate for the described functionality. The tool requires you to sign into Goodreads/Amazon in an interactive browser (expected for write actions).

ℹ Persistence & Privilege

The writer script creates and uses a local .browser-data directory to persist cookies/sessions for weeks/months as documented. That is expected for a browser-automation write tool, but it means the skill — once authorized — can perform actions on your Goodreads account without re-prompting. The skill is not marked always:true, but since disable-model-invocation is false (the platform default), an agent that is allowed to call skills autonomously could trigger write actions using the stored session; users should consider this operational risk.

版本历史

v1.0.0

Initial release: Read shelves/search/details via RSS + Write (rate, shelf, review, dates, progress) via Playwright

元数据

Slug goodreads-full

版本 1.0.0

许可证 MIT-0

累计安装 0

当前安装数 0

历史版本数 1

常见问题

Goodreads (Read + Write) 是什么？

Full Goodreads integration: read shelves, search books, get details/reviews via RSS, and write actions (rate, shelf, review, edit dates, progress) via Playwr... 它是一个面向 Claude Code / OpenClaw 的 AI Agent Skill 插件，目前累计下载 248 次。

如何安装 Goodreads (Read + Write)？

在 OpenClaw 或 Claude Code 对话框中运行命令「/install goodreads-full」即可一键安装，无需额外配置。

Goodreads (Read + Write) 是免费的吗？

是的，Goodreads (Read + Write) 完全免费，采用 MIT-0 许可证，可自由下载、安装和使用。

Goodreads (Read + Write) 支持哪些平台？

Goodreads (Read + Write) 跨平台运行，可在任意部署了 OpenClaw / Claude Code 的环境中使用（cross-platform）。

谁开发了 Goodreads (Read + Write)？

由 phuc-nt（@phuc-nt）开发并维护，当前版本 v1.0.0。

Goodreads (Read + Write)