# Weread > Use this skill whenever the user mentions 微信读书, WeRead, 书架, 读书时间, 读书笔记, 划线, or wants to do anything with their personal reading data. This includes: book search (搜书/找书), shelf inspection, reading progress and time, notes and highlights export, book reviews, reading statistics (weekly/monthly/annual/overall), personalized recommendations, and first-time API key setup. Always use this skill before running any WeRead-related commands — it provides the correct CLI abstractions, domain rules, and error handling patterns. - Skill: `shiquda/weread` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds add shiquda/weread` - Raw SKILL.md: https://api.skillmd.com/api/skills/shiquda/weread/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: shiquda (https://skillmd.com/u/shiquda) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/shiquda/weread --- # WeRead The local `weread` CLI is the only interface you need. It handles authentication, request shape, `skill_version`, JSON parsing, upgrade checks, and normalized errors — writing ad hoc `curl` requests would mean reimplementing all of that and losing the normalized error layer. Agents should use `--json` by default. Use human-readable output only when the user explicitly wants terminal-readable command output. For large outputs such as shelf, notebooks, bookmarks, or exports, write JSON or Markdown to a file first, then summarize the result in chat. Do not paste full large JSON payloads or full exported notes into the conversation. For `notes export`, use `--output ` by default. Only stream the export to stdout when the user explicitly asks to see the full export inline. ## First Decision Before any WeRead work, check auth and CLI health: ```bash weread doctor ``` If the `weread` command is missing, or if `auth_configured` is false, read `references/first-use.md` and guide the user through setup. ## Command Map ```bash weread search "三体" --scope book --count 10 weread book resolve "三体" --limit 5 weread book info weread book chapters weread book progress weread shelf list weread shelf recent --limit 10 weread readdata detail --mode monthly weread readdata summary --mode monthly weread notes notebooks --count 100 weread notes top --limit 20 weread notes bookmarks weread notes export --format markdown --output notes.md weread notes mine --count 20 weread notes underlines weread notes best --chapter-uid weread notes readreviews --reviews-json '[{"range":"900-2004","count":20}]' weread reviews list --type 1 --count 20 weread reviews single weread discover recommend --count 12 weread discover similar --count 12 weread discover friends --count 20 weread api list ``` When a supported API isn't covered by a first-class command, use the raw escape hatch: ```bash weread api call /store/search --param keyword=三体 --param scope=10 ``` ## When To Read References References are loaded on demand to keep startup context lean. Load them only when the task requires it: - **First-time setup, missing auth, or API Key questions**: read `references/first-use.md` - **Shelf totals, public/private counts, audiobook or article-collection handling**: read `references/domain-rules.md` - **Notes, highlights, bookmarks, personal ideas, public reviews, or exports**: read `references/domain-rules.md` - **Reading statistics, historical periods, cross-year ranges, or time-unit interpretation**: read `references/domain-rules.md` - **Deep links to books, chapters, highlights, or ideas**: read `references/domain-rules.md` ## Intent Routing ### Search - Find a book, get a `bookId`, or user says `搜书`/`找书`: `weread search "" --scope book` - Generic `搜一下` or mixed intent: `--scope all` - Web fiction or `网文`: `--scope fiction` - Audiobooks, podcasts, `听书`, `有声书`, or `专辑`: `--scope audio` - Authors: `--scope author` - Full-text search or `书里提到`: `--scope fulltext` - Book lists: `--scope list` - Official accounts: `--scope mp` - Articles: `--scope article` ### Book Details If the user gives a title rather than an ID, prefer `weread --json book resolve "" --limit 5` and use `items[].bookId`. - Metadata: `book info` - Chapter UIDs (needed for notes/highlights by chapter): `book chapters` - Reading progress: `book progress` — `progress` is an integer percent; `1` means 1%, only `100` means finished ### Shelf Use `weread --json shelf list`. For recent reading, use `weread --json shelf recent --limit 10`. For anything nuanced (public/private split, audiobook handling), read `references/domain-rules.md`. ### Reading Statistics Use `weread --json readdata summary --mode monthly` for common summaries, or `weread --json readdata detail` with `--mode weekly`, `monthly`, `annually`, or `overall`. Time fields in structured output are seconds. For historical or cross-period calculations, read `references/domain-rules.md`. ### Notes and Highlights - Overview across all books: `weread --json notes notebooks` - Books with the most personal notes/highlights: `weread --json notes top --limit 20` - Single-book export: `weread notes export <bookId> --format markdown --output <path>`; choose a local Markdown path and summarize counts/content instead of pasting the whole file - If manually combining data, use both `weread --json notes bookmarks <bookId>` and `weread --json notes mine <bookId>` - For counting rules, export limits, or popular highlight queries, read `references/domain-rules.md` ### Reviews Public reviews: `weread --json reviews list <bookId>` with `--type 0` (all) through `--type 4`. Single review: `weread --json reviews single <reviewId>`. ### Recommendations - Personalized: `weread --json discover recommend` - Similar books: `weread --json discover similar <bookId>` - Friends' reading activity: `weread --json discover friends`; continue with `nextMaxIdx` as `--max-idx` and reuse `synckey` for refreshes ## Pagination Stay shallow by default — only paginate further when the user explicitly asks for a complete export, a ranking, or a total that requires all pages. Use `--limit` for display size and `--all` where supported. For manual pagination, use `--json` and pass the native cursor from the previous JSON result: - Search: `hasMore == 1` → pass last item `searchIdx` as `--max-idx` - Notebooks: `hasMore == 1` → pass last `books[].sort` as `--last-sort` - Reviews: pass last review `idx` as `--max-idx` and returned `synckey` as `--synckey` - Similar: pass last item `idx` as `--max-idx` and `booksimilar.sessionId` as `--session-id` - Friends' activity: pass `nextMaxIdx` as `--max-idx`; reuse the returned `synckey` when refreshing the feed ## Error Handling The CLI normalizes errors to JSON: ```json { "ok": false, "skill_version": "1.0.4", "error": { "type": "missing_auth", "message": "..." } } ``` - `missing_auth`: read `references/first-use.md` and help configure the key - `upgrade_required`: stop immediately and follow `upgrade_info.message`; don't continue the original task until upgraded - `upstream_timeout`, `network_error`: these are retryable; the CLI already retries transient failures before returning the error - `api_error`, `http_error`, `invalid_json`: report the failure; retry only when repeating is safe ## User-Facing Output - Default to `--json`; use `--compact` when a command returns too much metadata for the task - Convert Unix timestamps to readable dates - Convert seconds to hours and minutes - Use numbered lists for search results, shelf entries, notes, reviews, and recommendations - Include WeRead deep links when useful; format rules are in `references/domain-rules.md`