huashu-weread skill
A reading advisor for agents on top of WeRead: picks from shelf and notes, learning paths, note digests and year reviews.
- 160 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The skill reads your WeRead shelf, notes and statistics through an API key and calls Tencent servers.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/huashu-wereadDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The skill reads your WeRead shelf, notes and statistics through an API key and calls Tencent servers.
This is third-party code. Review the repository files before installing.
What it does
huashu-weread adds a layer of working scenarios to the official WeRead skill from Tencent. It cross-reads a reader's shelf and notes: the shelf shows interests they filed themselves, the notes show which books they really read. That keeps the agent from recommending books you have already annotated. There are four scenarios. `advisor` picks the next book and spots gaps, `path` builds a ladder from introductory to current titles, `alchemy` turns scattered highlights into a structured digest, and `review` writes a period summary for social media and blogs. A quick question such as "what am I reading now" gets a one-line progress answer.
Who it is for. WeRead readers who want the agent to account for their shelf and notes instead of returning a generic book list.
Good fit when
- It is unclear what to read next: the agent matches your shelf against your notes and names five books that fill your gaps.
- You are learning a new field and want a route from introductory to current books.
- Highlights from one book are scattered and have to become a digest.
- At year end you need a reading review for social media or a blog.
Not a fit when
- You have no WeRead account: without a `WEREAD_API_KEY` there is no data.
- You only need book search and a shelf listing; the WeRead skill alone is enough.
- You read in another service or language: the skill works only with WeRead data.
Example request
Recommend my next product management book by matching my shelf against my notes, and confirm it is available in WeRead.Limitations
The official WeRead skill goes in first and `WEREAD_API_KEY` is set in the shell: every request goes to the `https://i.weread.qq.com/api/agent/gateway` gateway, so data is read from your Tencent account. The skill takes the API version from the official skill's `SKILL.md`, so a version bump can break requests. Texts, recommendations and the WeRead interface are in Chinese; there is no other-language mode. The style rules in `SKILL.md` point to a `SHARED-RULES.md` file that is not in the repository. The license is MIT.
How to disable. Delete the `huashu-weread-advisor` directory from the agent's skills folder. The official WeRead skill and the `WEREAD_API_KEY` variable stay and are removed separately.
FAQ
How do I install huashu-weread?
Install the official WeRead skill from weread.qq.com/r/weread-skills first and get a key. Then run `npx skills add alchaincyf/huashu-weread`.
How does it differ from the official WeRead skill?
The official skill exposes 8 API methods: search, shelf, notes, reviews, statistics. This one adds scenarios on top. For example, before advising it checks which books you have already annotated.
Which scenarios are there?
Four: `advisor` for the next book, `path` for a learning route, `alchemy` for a highlights digest and `review` for a period summary. Short questions about the current book are understood too.
How does the skill pick a scenario?
By the wording of the request. "What to read next" starts `advisor`, "I want to understand a topic" starts `path`, "collect my notes" starts `alchemy` and "year in review" starts `review`.
Does the skill suggest books that are not in WeRead?
Before advising, the skill searches the WeRead store. If a book is missing, it says so and names legal routes: a print or English edition, the author's course, a library.
Discussion
No questions or reviews yet.
Related
SkillsShelf, highlights and reading stats from WeChat Reading in a chat with your agent: the official Tencent skill
Readwise skills help agents triage a reading inbox, discuss books and connect highlights across saved sources
An MCP server for WeChat Reading: your AI agent gets your bookshelf, notes, highlights and top reviews
A skill set for notes and plans in Chinese: iMandalArt cards, BIRD knowledge addresses, a keyword graph and an eight-page A4 booklet
Qiushi Skill
求是 Skill
A set of methodology skills: investigate the facts first, find the main contradiction, validate in practice and finish the job
Twenty-seven Chinese-language skills for development, thinking, learning, writing, visuals, branding and working with agents
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| huashu-weread (this card) | no | 160 | ||
| WeChatReading | yes | 282 | the official Tencent skill with API methods; huashu-weread adds recommendation, route and digest scenarios | |
| mcp-server-weread | no | key is optional | 584 | an MCP server that returns the shelf and notes; huashu-weread is a skill with scenarios on top of that data |
README in short
The method rests on three signals: read or untouched, depth by note count, and freshness by last-opened time. Before fixing the number of books and the tone of a review the skill asks clarifying questions, and on API errors it retries once.
README badge
Original SKILL.md
---
name: huashu-weread-advisor
description: 微信读书高阶顾问。在底层 weread skill 的原子 API 之上，提供四类工作流：基于已读做个性化进阶推荐（advisor）、给方向规划入门到前沿的阶梯书单（path）、把零散划线想法提炼成读书笔记总结（alchemy）、做季度/年度阅读复盘并生成可发朋友圈/公众号的文章（review）。核心方法是「书架 + 笔记交叉分析」——书架揭示用户主动分类的兴趣，笔记数据揭示「真读过的」vs「只放着的」。当用户说「推荐书」「下一本读啥」「该读什么」「想搞懂 X 这个领域」「整理我的笔记」「这本书我记住了啥」「我今年读了什么」「读书复盘」「年度盘点」时触发。即使用户只是说「不知道读啥」「有没有相关的书」「帮我看看这本读完了吗」「这个领域我入门了吗」也应触发。
---
# huashu-weread-advisor
把原子的微信读书 API 变成一个真正读懂你的读书顾问。
## 定位
底层 weread skill 提供原子接口（搜索、书架、笔记、点评、推荐、阅读统计），本 skill 在其之上做**工作流编排**，把原始数据转成对用户有消费价值的产出。
## 前置依赖
- 必须先有 `WEREAD_API_KEY` 环境变量（在用户 shell 中 export）
- 所有 API 调用走 `POST https://i.weread.qq.com/api/agent/gateway`
- 请求 body 必须带 `skill_version` 字段——**值的权威来源**：`~/.claude/skills/weread/SKILL.md` 顶部 frontmatter 的 `version` 字段（当前 `1.0.3`，会变；别从 prompt 或老模板里抄）
- 接口文档和参数详情见底层 weread skill：`~/.claude/skills/weread/SKILL.md`
## 核心方法论（所有 workflow 共享）
### 1. 书架和笔记是两个数据源，必须交叉
| 数据源 | 接口 | 揭示什么 |
|--------|------|---------|
| 书架 | `/shelf/sync` | 用户**主动分类**的兴趣方向 + 加入了什么 |
| 笔记 | `/user/notebooks` | 用户**真读过**的书 + 读得多深（笔记条数） |
| 进度 | `/book/getprogress` | 某本书读到哪、累计读了多久 |
| 统计 | `/readdata/detail` | 周/月/年阅读时长、天数、主题偏好 |
**关键洞察**：很多书在书架但没动，很多书没在书架（借/试读）但深读了。只看书架会漏掉重要信号。
**实战例子**：花叔的 Kandel《追寻记忆的痕迹》27 条笔记，书架的「心理学」分类里根本没列，但其实是他在神经科学领域读得最深的一本。如果只看书架做推荐，会误判他的真实知识地图。
### 2. 「最近读什么」≠「书架主题」
用户的当前兴趣可能和书架分类完全不一致。永远用 `readUpdateTime` 倒序看最近 30 天在动什么书，再做推荐。
### 3. 推荐必附 weread:// 深度链接
`weread://reading?bId={bookId}` 让用户一键打开。链接格式详见底层 weread skill 的「深度链接（URL Schema）」章节。
### 4. 推荐前必须验证微信读书是否上架