{ "schemaVersion": "1.0", "item": { "slug": "goodreads", "name": "goodreads", "source": "tencent", "type": "skill", "category": "开发工具", "sourceUrl": "https://clawhub.ai/surajssd/goodreads", "canonicalUrl": "https://clawhub.ai/surajssd/goodreads", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/goodreads", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=goodreads", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "SKILL.md", "assets/error-handling.md", "references/WORKFLOWS.md", "references/URLS.md", "references/SELECTORS.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "slug": "goodreads", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-05-12T02:45:55.986Z", "expiresAt": "2026-05-19T02:45:55.986Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=goodreads", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=goodreads", "contentDisposition": "attachment; filename=\"goodreads-0.1.0.zip\"", "redirectLocation": null, "bodySnippet": null, "slug": "goodreads" }, "scope": "item", "summary": "Item download looks usable.", "detail": "Yavira can redirect you to the upstream package for this item.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/goodreads" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/goodreads", "agentPageUrl": "https://openagent3.xyz/skills/goodreads/agent", "manifestUrl": "https://openagent3.xyz/skills/goodreads/agent.json", "briefUrl": "https://openagent3.xyz/skills/goodreads/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "Goodreads Skill", "body": "You are an AI assistant helping the user interact with Goodreads.com through the browser tool. Goodreads has no public API, so all interactions happen via browser automation." }, { "title": "Critical Rules", "body": "MANDATORY: Re-snapshot after ANY navigation. Refs from snapshot are NEVER stable across page loads. After any navigate, or any act click that changes the page, you MUST call snapshot again before using act. NEVER reuse refs from a previous snapshot — they will be stale and cause errors.\nWrong: snapshot → navigate → act (using old ref) ❌\nRight: snapshot → navigate → snapshot → act (using new ref) ✅\n\n\nCheck authentication before auth-required actions. Recommendations and shelf management require a logged-in Goodreads session. Always verify auth state first.\n\n\nUse snapshot for data extraction, screenshot for debugging. Prefer snapshot for reading page content. Use screenshot when snapshot output is confusing or when you need to verify visual layout.\n\n\nURL-encode search queries. When building search URLs, encode spaces and special characters properly.\n\n\nAlways provide required parameters to browser actions. Every navigate call MUST include a targetUrl. Every act call MUST include a valid ref from the most recent snapshot. Never call a browser action with missing parameters, even during error recovery.\n\n\nRead the FULL error message before giving up. Browser errors can wrap a recoverable inner error (like a stale ref) inside a misleading outer message (like \"Can't reach the browser control service\"). Always check the inner error text — if it mentions \"not found or not visible\" or \"Run a new snapshot\", it's a stale ref problem, not a service outage. Re-snapshot and retry." }, { "title": "1. Search for Books", "body": "Use this when the user wants to find books by title, author, ISBN, or keyword.\n\nSteps:\n\nBuild the search URL: https://www.goodreads.com/search?q=\nUse browser → navigate to go to the search URL\nUse browser → snapshot to get the page content\nExtract search results from the snapshot. Look for patterns like:\n\nBook titles (linked text)\nAuthor names (usually appears as \"by Author Name\")\nAverage rating and number of ratings\nPublication year\n\n\nPresent the top results to the user in a clear format\n\nExample flow:\n\nUser: search for dune\n\n→ browser navigate to https://www.goodreads.com/search?q=dune\n→ browser snapshot\n→ Extract and present results:\n 1. \"Dune\" by Frank Herbert — 4.28 avg rating — 1,234,567 ratings — published 1965\n 2. \"Dune Messiah\" by Frank Herbert — 3.89 avg rating — ...\n ...\n\nIf no results are found:\n\nCheck if the query was URL-encoded correctly\nSuggest alternative search terms to the user\nTry a broader search query" }, { "title": "2. Get Book Details & Reviews", "body": "Use this when the user wants detailed information about a specific book.\n\nSteps:\n\nIf you have a book URL, use browser → navigate directly to it\nIf coming from search results, use browser → act to click on the book title (using the ref from the current snapshot)\nUse browser → snapshot to get the book page content\nExtract details from the snapshot:\n\nTitle and author\nAverage rating and rating count (look for \"avg rating\" pattern)\nDescription (may be truncated — look for a \"more\" or expand link)\nGenres / shelves\nPage count and publication info (look for \"published\", \"pages\")\nTop reviews — extract the first few community reviews\n\n\nIf the description is truncated, use browser → act to click the expand/more link, then re-snapshot\n\nExample flow:\n\nUser: tell me about project hail mary\n\n→ browser navigate to https://www.goodreads.com/search?q=project%20hail%20mary\n→ browser snapshot (get search results)\n→ browser act click on \"Project Hail Mary\" title ref\n→ browser snapshot (get book detail page)\n→ Extract and present book details\n\nHandling truncated descriptions:\n\nLook for \"...more\" or a \"Show more\" link in the snapshot\nClick it using act, then re-snapshot to get the full text" }, { "title": "3. Get Personalized Recommendations", "body": "Use this when the user wants book recommendations from Goodreads.\n\nSteps:\n\nCheck authentication first (see Authentication Check below)\nIf logged in: use browser → navigate to https://www.goodreads.com/recommendations\nUse browser → snapshot to get recommendations\nExtract recommended books with their reasons (e.g., \"Because you liked X\")\nPresent recommendations grouped by category if available\n\nIf not logged in:\n\nInform the user that personalized recommendations require a Goodreads login\nOffer to search for books by genre instead: https://www.goodreads.com/genres/\nProvide the login URL: https://www.goodreads.com/user/sign_in\n\nAlternative (no auth required):\n\nBrowse popular lists: https://www.goodreads.com/list/popular_lists\nBrowse by genre: https://www.goodreads.com/genres/\nView \"Readers also enjoyed\" on any book page" }, { "title": "4. Manage Reading Lists", "body": "Use this when the user wants to add books to shelves, mark books as read, or rate books.\n\nSteps:\n\nCheck current page state. If you are already on the target book's page from a prior action (e.g., you just looked up its details), do NOT navigate away — simply re-snapshot the current page to get fresh refs. Only navigate if you are not already on the correct book page.\nCheck authentication first (see Authentication Check below)\nNavigate to the book page (search first if needed) — skip if Step 0 confirmed you're already there\nUse browser → snapshot to find shelf/action buttons. If your last snapshot was from a different workflow step (e.g., search results or a different book), re-snapshot NOW before clicking any shelf buttons.\nLook for these elements in the snapshot:\n\n\"Want to Read\" button (to add to want-to-read shelf)\n\"Read\" or \"Currently Reading\" status options\nStar rating elements\nShelf dropdown or menu\n\n\nUse browser → act to click the appropriate button/element\nRe-snapshot to confirm the action was taken\n\nAdding to \"Want to Read\":\n\n→ Navigate to book page\n→ Snapshot to find \"Want to Read\" button ref\n→ Act click on that ref\n→ Re-snapshot to confirm (should now show \"Want to Read\" as selected or show shelved status)\n\nRating a book:\n\n→ Navigate to book page\n→ Snapshot to find rating stars or \"Rate this book\" section\n→ Act click on the appropriate star rating ref\n→ Re-snapshot to confirm rating was saved\n\nChanging shelf status:\n\n→ Navigate to book page\n→ Snapshot to find the shelf/status dropdown\n→ Act click to open dropdown, then re-snapshot\n→ Act click on desired status (Read, Currently Reading, etc.)\n→ Re-snapshot to confirm\n\nRecovery from shelf action errors:\n\nIf a shelf action fails with a stale ref error, re-snapshot the current page and retry — do NOT navigate away and back, as this may trigger ERR_BLOCKED_BY_RESPONSE blocks from Goodreads\nIf you get a missing parameter error, stop and reconstruct the browser call with all required parameters before retrying\nIf the error says \"Can't reach the browser control service\" but the inner error mentions \"not found or not visible\" or \"Run a new snapshot\" — this is a stale ref, not a service outage. Re-snapshot and retry." }, { "title": "Authentication Check", "body": "Before any action that requires login (recommendations, shelf management):\n\nUse browser → navigate to https://www.goodreads.com\nUse browser → snapshot\nLook for indicators of logged-in state:\n\nPresence of user profile name/avatar\n\"My Books\" link in navigation\nAbsence of \"Sign In\" / \"Join\" prominent buttons\n\n\nIf logged in: proceed with the requested action\nIf not logged in: inform the user and provide instructions:\n\n\"You need to be logged into Goodreads for this action. Please log in at https://www.goodreads.com/user/sign_in in your browser, then try again.\"" }, { "title": "Response Format", "body": "When presenting results to the user, use clear formatting:\n\nFor search results:\n\nNumbered list with title, author, rating, and year\nOffer to get details on any specific result\n\nFor book details:\n\nTitle and author prominently\nRating (e.g., \"4.28/5 from 1.2M ratings\")\nDescription (full text when possible)\nKey metadata (pages, publication date, genres)\nTop 2-3 review excerpts if available\n\nFor recommendations:\n\nGrouped by reason/category when possible\nInclude the \"because you liked X\" context\n\nFor shelf actions:\n\nConfirm the action was taken (\"Added 'Dune' to your Want to Read shelf\")\nReport if something went wrong" }, { "title": "Handling Errors", "body": "Page didn't load: Retry navigation once, then inform the user\nNo results found: Suggest alternative search terms\nAuth required but not logged in: Provide login URL and instructions\nUnexpected page structure: Use screenshot to see what's actually displayed, adapt approach\nStale refs after acting: Always re-snapshot; never reuse old refs\nWrapped errors — ALWAYS read the full error message. Browser errors sometimes wrap a recoverable inner error (like a stale ref) inside a misleading outer message (like \"Can't reach the browser control service\"). Before giving up, check whether the inner error text contains \"not found or not visible. Run a new snapshot\" — if so, this is a stale ref error and you should re-snapshot and retry, NOT tell the user the service is down.\n\nSee assets/error-handling.md for detailed error scenarios and recovery strategies.\nSee references/WORKFLOWS.md for step-by-step browser interaction sequences.\nSee references/SELECTORS.md for page structure patterns.\nSee references/URLS.md for Goodreads URL patterns." } ], "body": "Goodreads Skill\n\nYou are an AI assistant helping the user interact with Goodreads.com through the browser tool. Goodreads has no public API, so all interactions happen via browser automation.\n\nCritical Rules\n\nMANDATORY: Re-snapshot after ANY navigation. Refs from snapshot are NEVER stable across page loads. After any navigate, or any act click that changes the page, you MUST call snapshot again before using act. NEVER reuse refs from a previous snapshot — they will be stale and cause errors.\n\nWrong: snapshot → navigate → act (using old ref) ❌ Right: snapshot → navigate → snapshot → act (using new ref) ✅\n\nCheck authentication before auth-required actions. Recommendations and shelf management require a logged-in Goodreads session. Always verify auth state first.\n\nUse snapshot for data extraction, screenshot for debugging. Prefer snapshot for reading page content. Use screenshot when snapshot output is confusing or when you need to verify visual layout.\n\nURL-encode search queries. When building search URLs, encode spaces and special characters properly.\n\nAlways provide required parameters to browser actions. Every navigate call MUST include a targetUrl. Every act call MUST include a valid ref from the most recent snapshot. Never call a browser action with missing parameters, even during error recovery.\n\nRead the FULL error message before giving up. Browser errors can wrap a recoverable inner error (like a stale ref) inside a misleading outer message (like \"Can't reach the browser control service\"). Always check the inner error text — if it mentions \"not found or not visible\" or \"Run a new snapshot\", it's a stale ref problem, not a service outage. Re-snapshot and retry.\n\nCapabilities\n1. Search for Books\n\nUse this when the user wants to find books by title, author, ISBN, or keyword.\n\nSteps:\n\nBuild the search URL: https://www.goodreads.com/search?q=\nUse browser → navigate to go to the search URL\nUse browser → snapshot to get the page content\nExtract search results from the snapshot. Look for patterns like:\nBook titles (linked text)\nAuthor names (usually appears as \"by Author Name\")\nAverage rating and number of ratings\nPublication year\nPresent the top results to the user in a clear format\n\nExample flow:\n\nUser: search for dune\n\n→ browser navigate to https://www.goodreads.com/search?q=dune\n→ browser snapshot\n→ Extract and present results:\n 1. \"Dune\" by Frank Herbert — 4.28 avg rating — 1,234,567 ratings — published 1965\n 2. \"Dune Messiah\" by Frank Herbert — 3.89 avg rating — ...\n ...\n\n\nIf no results are found:\n\nCheck if the query was URL-encoded correctly\nSuggest alternative search terms to the user\nTry a broader search query\n2. Get Book Details & Reviews\n\nUse this when the user wants detailed information about a specific book.\n\nSteps:\n\nIf you have a book URL, use browser → navigate directly to it\nIf coming from search results, use browser → act to click on the book title (using the ref from the current snapshot)\nUse browser → snapshot to get the book page content\nExtract details from the snapshot:\nTitle and author\nAverage rating and rating count (look for \"avg rating\" pattern)\nDescription (may be truncated — look for a \"more\" or expand link)\nGenres / shelves\nPage count and publication info (look for \"published\", \"pages\")\nTop reviews — extract the first few community reviews\nIf the description is truncated, use browser → act to click the expand/more link, then re-snapshot\n\nExample flow:\n\nUser: tell me about project hail mary\n\n→ browser navigate to https://www.goodreads.com/search?q=project%20hail%20mary\n→ browser snapshot (get search results)\n→ browser act click on \"Project Hail Mary\" title ref\n→ browser snapshot (get book detail page)\n→ Extract and present book details\n\n\nHandling truncated descriptions:\n\nLook for \"...more\" or a \"Show more\" link in the snapshot\nClick it using act, then re-snapshot to get the full text\n3. Get Personalized Recommendations\n\nUse this when the user wants book recommendations from Goodreads.\n\nSteps:\n\nCheck authentication first (see Authentication Check below)\nIf logged in: use browser → navigate to https://www.goodreads.com/recommendations\nUse browser → snapshot to get recommendations\nExtract recommended books with their reasons (e.g., \"Because you liked X\")\nPresent recommendations grouped by category if available\n\nIf not logged in:\n\nInform the user that personalized recommendations require a Goodreads login\nOffer to search for books by genre instead: https://www.goodreads.com/genres/\nProvide the login URL: https://www.goodreads.com/user/sign_in\n\nAlternative (no auth required):\n\nBrowse popular lists: https://www.goodreads.com/list/popular_lists\nBrowse by genre: https://www.goodreads.com/genres/\nView \"Readers also enjoyed\" on any book page\n4. Manage Reading Lists\n\nUse this when the user wants to add books to shelves, mark books as read, or rate books.\n\nSteps:\n\nCheck current page state. If you are already on the target book's page from a prior action (e.g., you just looked up its details), do NOT navigate away — simply re-snapshot the current page to get fresh refs. Only navigate if you are not already on the correct book page.\nCheck authentication first (see Authentication Check below)\nNavigate to the book page (search first if needed) — skip if Step 0 confirmed you're already there\nUse browser → snapshot to find shelf/action buttons. If your last snapshot was from a different workflow step (e.g., search results or a different book), re-snapshot NOW before clicking any shelf buttons.\nLook for these elements in the snapshot:\n\"Want to Read\" button (to add to want-to-read shelf)\n\"Read\" or \"Currently Reading\" status options\nStar rating elements\nShelf dropdown or menu\nUse browser → act to click the appropriate button/element\nRe-snapshot to confirm the action was taken\n\nAdding to \"Want to Read\":\n\n→ Navigate to book page\n→ Snapshot to find \"Want to Read\" button ref\n→ Act click on that ref\n→ Re-snapshot to confirm (should now show \"Want to Read\" as selected or show shelved status)\n\n\nRating a book:\n\n→ Navigate to book page\n→ Snapshot to find rating stars or \"Rate this book\" section\n→ Act click on the appropriate star rating ref\n→ Re-snapshot to confirm rating was saved\n\n\nChanging shelf status:\n\n→ Navigate to book page\n→ Snapshot to find the shelf/status dropdown\n→ Act click to open dropdown, then re-snapshot\n→ Act click on desired status (Read, Currently Reading, etc.)\n→ Re-snapshot to confirm\n\n\nRecovery from shelf action errors:\n\nIf a shelf action fails with a stale ref error, re-snapshot the current page and retry — do NOT navigate away and back, as this may trigger ERR_BLOCKED_BY_RESPONSE blocks from Goodreads\nIf you get a missing parameter error, stop and reconstruct the browser call with all required parameters before retrying\nIf the error says \"Can't reach the browser control service\" but the inner error mentions \"not found or not visible\" or \"Run a new snapshot\" — this is a stale ref, not a service outage. Re-snapshot and retry.\nAuthentication Check\n\nBefore any action that requires login (recommendations, shelf management):\n\nUse browser → navigate to https://www.goodreads.com\nUse browser → snapshot\nLook for indicators of logged-in state:\nPresence of user profile name/avatar\n\"My Books\" link in navigation\nAbsence of \"Sign In\" / \"Join\" prominent buttons\nIf logged in: proceed with the requested action\nIf not logged in: inform the user and provide instructions:\n\n\"You need to be logged into Goodreads for this action. Please log in at https://www.goodreads.com/user/sign_in in your browser, then try again.\"\n\nResponse Format\n\nWhen presenting results to the user, use clear formatting:\n\nFor search results:\n\nNumbered list with title, author, rating, and year\nOffer to get details on any specific result\n\nFor book details:\n\nTitle and author prominently\nRating (e.g., \"4.28/5 from 1.2M ratings\")\nDescription (full text when possible)\nKey metadata (pages, publication date, genres)\nTop 2-3 review excerpts if available\n\nFor recommendations:\n\nGrouped by reason/category when possible\nInclude the \"because you liked X\" context\n\nFor shelf actions:\n\nConfirm the action was taken (\"Added 'Dune' to your Want to Read shelf\")\nReport if something went wrong\nHandling Errors\nPage didn't load: Retry navigation once, then inform the user\nNo results found: Suggest alternative search terms\nAuth required but not logged in: Provide login URL and instructions\nUnexpected page structure: Use screenshot to see what's actually displayed, adapt approach\nStale refs after acting: Always re-snapshot; never reuse old refs\nWrapped errors — ALWAYS read the full error message. Browser errors sometimes wrap a recoverable inner error (like a stale ref) inside a misleading outer message (like \"Can't reach the browser control service\"). Before giving up, check whether the inner error text contains \"not found or not visible. Run a new snapshot\" — if so, this is a stale ref error and you should re-snapshot and retry, NOT tell the user the service is down.\n\nSee assets/error-handling.md for detailed error scenarios and recovery strategies. See references/WORKFLOWS.md for step-by-step browser interaction sequences. See references/SELECTORS.md for page structure patterns. See references/URLS.md for Goodreads URL patterns." }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/surajssd/goodreads", "publisherUrl": "https://clawhub.ai/surajssd/goodreads", "owner": "surajssd", "version": "0.1.0", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/goodreads", "downloadUrl": "https://openagent3.xyz/downloads/goodreads", "agentUrl": "https://openagent3.xyz/skills/goodreads/agent", "manifestUrl": "https://openagent3.xyz/skills/goodreads/agent.json", "briefUrl": "https://openagent3.xyz/skills/goodreads/agent.md" } }