Turn the atomic WeRead APIs into a reading advisor that truly understands you.
Positioning
The underlying weread skill provides atomic interfaces (search, bookshelf, notes, reviews, recommendations, reading stats), and this skill builds on top of it to doworkflow orchestration, turning raw data into output with consumption value for users.
Prerequisites
- There must first be the
WEREAD_API_KEYenvironment variable (exported in the user's shell) - All API calls go through
POST https://i.weread.qq.com/api/agent/gateway - The request body must include the
skill_versionfield——authoritative source of the value：~/.claude/skills/weread/SKILL.mdAt the top of the frontmatter, theversionfield (currently1.0.3, it will change; don't copy it from the prompt or old templates) - For interface documentation and parameter details, see the underlying weread skill:
~/.claude/skills/weread/SKILL.md
Core methodology (shared by all workflows)
1. Bookshelf and notes are two data sources, and they must be cross-referenced
| Data source | Interface | What it reveals |
|---|---|---|
| Bookshelf | /shelf/sync |
The user'sactively categorizedinterest directions + what has been added |
| Notes | /user/notebooks |
Books the userhas actually read+ how deeply they read (number of notes) |
| Progress | /book/getprogress |
How far into a book someone has read, and cumulative reading time |
| Stats | /readdata/detail |
Weekly/monthly/yearly reading duration, days, topic preferences |
Key insight: many books are on the bookshelf but untouched, and many books are not on the bookshelf (borrowed/trial-read) but read deeply. Looking only at the bookshelf will miss important signals.
Real-world example: Huashu's 27 notes on Kandel's 'In Search of Memory'—the 'Psychology' category on the bookshelf doesn't list it at all, but it is actually the book he has read most deeply in the neuroscience field. If recommendations are made based only on the bookshelf, his real knowledge map will be misjudged.
2. 'What has been read recently' ≠ 'bookshelf topics'
The user's current interests may be completely inconsistent with the bookshelf categories. Always use readUpdateTime in reverse order to see what books have been active in the last 30 days, then make recommendations.
3. Recommendations must include a weread:// deep link
weread://reading?bId={bookId} so users can open it with one click. For the link format, see the 'Deep Links (URL Schema)' section of the underlying weread skill.
4. Before recommending, you must verify whether WeRead has it available
Use /store/search to search and confirm. For those available, attach a weread:// link; for those not available, clearly tell the user legitimate alternatives (buy the paper/English edition/author's public course/library).Never recommend pirated resources。
5. Output follows Huashu's language style
- No piling up, no dashes (≤ 2 in the whole text), strong human feel
- Use 「」 instead of ""
- Do not use AI structural words like 'first/second/in summary'
- Do not use 'to put it plainly/in simple terms/in other words'
- Do not overuse bold in markdown
- See
/04-写作参考/SHARED-RULES.md
Checkpoint design principles
All workflows must insert a user confirmation gate where "branching affects the nature of the output," to prevent the AI's defaults from going off track:
- Number of recommendations branching: advisor recommending 3 books vs 8 books is a completely different experience; do not default to 5 books, ask first
- Platform tone branching: a review article posted to Moments/WeChat Official Account/Xiaohongshu/video script has very different tones; confirm before writing
- Level judgment branching: the path workflow shows the user the judgment "I thought you were a beginner" and lets them confirm or correct it
- Data volume branching: when alchemy cross-topic patterns pull out 50+ highlights, first summarize the topics and let the user choose a subset; do not default to clustering them all
- Unavailable book handling branching: whether recommendations should include unavailable books (the user may only want books they can open and read right away)
Checkpoints are not "ask at every step." For small everyday decisions (which book goes in the first tier, what verb to use), the AI decides on its own and does not bother the user. The rule is:Only ask when the choice affects the nature of the output。
If the user's original prompt already clearly specifies it ("recommend 3 available books to post on WeChat Official Account"), skip all related checkpoints.
Subcommand routing
| What the user says | Which workflow to take |
|---|---|
| Recommend books / what to read next / don't know what to read / want to read in direction X | advisor.md |
| Want to understand the field of X / systematically learn X / get started with X from scratch | path.md |
| Organize my notes / what did I remember from this book / extract highlights for this topic | alchemy.md |
| What did I read this year / quarterly review / annual roundup / write a review | review.md |
| Which book am I reading now / what have I been reading recently | Lightweight direct answer (see below) |
Lightweight direct answer: "Which book am I reading now"
Do not take a workflow; directly:
/shelf/syncget the entire bookshelf- sort by
readUpdateTimein reverse order and take top 5 - use the most recent book to call
/book/getprogressget chapters/progress/cumulative time - Reply in one sentence: "You are reading X, now at chapter N, progress X%, cumulative reading time X hours," with a weread:// link
- Also mention a few other books read in the past week, to reveal topical tendencies
Shared submodules
- shared/knowledge-map.md: how to understand a person's knowledge map (three data sources × three cross signals)
- shared/shelf-cross-notes.md: Python code templates and topic keyword groups for cross-analysis of bookshelf + notes
Example
- examples/advisor-neuroscience.md: a complete review of Huashu's "How Neuroscience Can Go Further" case, including steps, output, and why it was recommended this way
Exceptions and boundary conditions
Exceptions are commonly encountered in practice. The following are global general fallbacks, shared by all workflows. Each workflow's specific exceptions are at the end of its own document.
| Scenario | Trigger condition | Handling action |
|---|---|---|
WEREAD_API_KEY is not set |
The environment variable does not exist or does not start with wrk- start |
Error: "Please first export WEREAD_API_KEY=<your apikey>, obtained from the WeRead backend," terminate |
API returns errcode != 0 |
API error | Show the Chinese error message, retry once; if it still fails, inform the user and stop the current workflow |
Interface returned upgrade_info |
The server requires a skill version upgrade | Pause the current operation, follow upgrade_info.message and retry after completing the upgrade,do not ignore |
/store/search Response parsing |
Parse the returned JSON | The top level is not books[]! The actual structure is results[], classified by section. To get the listed ones:results[?title=='电子书'].books[*].bookInfo; to get the unlisted ones:title=='待上架'. Each book's bookId is in bookInfo.bookId。Do not use res.get('books', []), it will return all 0 results |
/store/search Multiple candidates |
The same keyword returns ≥ 3 book candidates | By default take the one with the highest readingCount andthe author exactly matching(an author mismatch is treated as zero results, to avoid pitfalls like "Co-Intelligence" incorrectly matching "Collaborative Intelligence"),clearly inform the user"I used the book 《X》 by Y, bookId=Z, tell me if that's wrong" |
/store/search Zero results |
Still zero after a complete search failure + keyword adjustment + author filtering | Mark as "not listed", handle it according to the advisor's "legitimate alternative path" rules,never recommend pirated copies |
| notebooks is completely empty | New user / has never taken notes | Degrade: use only /shelf/sync to infer, butclearly inform the user"You haven't taken any notes, so I can only guess your interests from your bookshelf, and the accuracy will be somewhat worse" |
| The bookshelf is completely empty | Brand-new user | Do not run advisor / review / alchemy, suggest reading a few books first; or go directly into the path workflow to plan from scratch |
| Interface pagination not fully fetched | /user/notebooks has hasMore |
Use lastSort to continue paging (parameters flattened,do not wrap in params )); when the total exceeds 500 books, warn the user |
readUpdateTime = 0 |
Added to the bookshelf but never opened | Treat as "unread", do not include in the "recently active" sorting, but still count it as "on the bookshelf but untouched" |
| The book title given by the user cannot be found | alchemy / any scenario with a named book | Search fuzzily first (remove punctuation / remove subtitle); if still not found, give a candidate list for the user to choose from |
| The topic term is too broad or too narrow | "Business" and "Humanities" are too broad; obscure terms are too narrow | Too broad: ask the user to refine the direction; too narrow: inform them that WeRead coverage is thin, and suggest combining with paper / Kindle |
Principles: For anomalies, inform the user first, then handle according to the rules; never silently skip or silently fail; for the specific meaning of interface errors, see the underlying weread skill's references/ documentation.
Data display specifications (mandatory)
All workflow outputs to the user must comply with:
- Unix timestamp（
readUpdateTime/finishTime/createTimeetc.) → convert toYYYY-MM-DD, directly displaying numbers is prohibited - Reading duration fieldThe unit is seconds → convert to "X hours Y minutes", when hours are zero write only minutes
- Progress fieldDisplay as
X% - bookId Naked numbers must not appear in front of users; either turn them into weread:// links or hide them inside markdown links
Calling convention
No matter which workflow is used, the first step is always to read SKILL.md this file + the corresponding workflow file + shared/knowledge-map.md, and only then start calling the API. Do not make recommendations based on impressions; all recommendations must be supported by data.
Version self-check (silent)
This section is for the AI agent: before using this skill each time, first make an offline judgment—read the .last-update-check file under this skill directory (the directory containing SKILL.md) (its content is a single line with the date YYYY-MM-DD). If the file exists and is less than 30 days old, skip this section and get straight to work, without mentioning anything update-related to the user.
When it is expired or the file does not exist, and only then:
- This directory is not a git clone (no
.gitor no origin) → write today's date and then skip this section - Compare versions:
git -C <本目录> rev-parse HEADandgit -C <本目录> ls-remote origin HEAD - Regardless of the result, write today's date into
.last-update-check - If the two match → say nothing; if confirmed to be behind → first complete the user's current task, then add one sentence afterward: "This skill has a new version, you can use
git -C <本目录> pull --ff-onlyto update." Whether to update is up to the user; do not proactively perform the update