Claude Code Skill 详解：微信读书助手（weread）

一、Skill 是什么

Skill（技能）是 Claude Code 的扩展机制，允许用户定义可复用的专业能力。它比 Command（命令）更强大：

一句话理解：Command 是快捷操作按钮，Skill 是会自动识别场景并执行标准流程的领域专家。

二、weread Skill 说明

"让 AI 成为你的阅读搭档" — 连接微信读书账号，让 AI 助手随时查阅你的阅读记录。

功能

通过 Agent API Gateway 调用微信读书接口，提供六大核心能力：

此外还支持：章节热门划线（查看热门划线及想法）、书籍点评（查看公开点评）。

触发条件

当用户提到以下关键词时，自动触发：

• 微信读书、读书、书架、笔记、划线、书评
• 阅读统计、阅读时长、阅读偏好
• 搜书、找书、推荐书、书单
• weRead、weread

三、API 接口规范

统一入口

POST https://i.weread.qq.com/api/agent/gateway

鉴权

• Header：Authorization: Bearer $WEREAD_API_KEY
• WEREAD_API_KEY 从环境变量获取，格式 wrk-xxxxxxxx
• 若未设置，提示用户：export WEREAD_API_KEY=<你的apikey>

请求格式

curl -X POST "https://i.weread.qq.com/api/agent/gateway" \
  -H "Authorization: Bearer $WEREAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api_name": "/store/search", "keyword": "三体", "count": 10, "skill_version": "1.0.3"}'

关键规则

1. 版本上报：每次请求 body 必须包含 "skill_version": "1.0.3"（取 SKILL.md 顶部 version 字段的值），用于服务端检查版本更新
2. 升级提醒：如果回包中出现 upgrade_info 字段，必须立即暂停当前操作，按照 upgrade_info.message 中的指引完成升级，升级完成后再重新执行用户请求
3. 参数平铺：业务参数必须和 api_name、skill_version 放在同一层；不要包在 params、data、body 等对象里。只有接口文档明确声明的数组/对象字段（如 /book/readreviews 的 reviews）才允许作为业务字段传入
4. 能力文档预检：调用任何接口前，必须先阅读对应说明文件（如阅读统计先读 readdata.md，书架先读 shelf.md），确认接口参数、字段含义、单位和工作流；禁止仅凭字段名或经验猜测含义
5. 字段解释优先级：以对应说明文件中的字段说明为准；如果回包字段名和直觉含义冲突，必须服从说明文件，不得直接翻译字段名
6. bookId 解析：用户输入书名时，先调 /store/search 获取 bookId，再执行后续操作
7. 书架数量：必须按 books.length + albums.length + (mp 非空 ? 1 : 0) 计算；albums[] 是专辑/有声书，也属于书架里的书
8. 结果展示：列表用编号展示方便选择；展示接口回包信息时，字段禁止直接翻译，应该参考文件中的说明内容提供
9. 上下文衔接：对话中记住已查询的 bookId，后续操作无需用户重复提供
10. 深度链接：展示划线、想法、章节等内容时，拼接跳转链接方便用户在 App 中打开
11. 数据展示规范：

• 时间戳：所有 Unix 时间戳字段展示时须转为 YYYY-MM-DD 格式，不得直接展示原始数字
• 阅读时长：单位为秒，展示时转为"X小时Y分钟"格式

响应格式

• JSON，回包经过字段裁剪，只返回核心字段
• errcode 非 0 时表示错误，给出中文提示
• 发送 {"api_name": "/_list"} 可查看所有可用接口及参数定义

接口总览

四、快速安装

方式一：自动安装（推荐）

将以下指令发送给 AI 助手即可自动安装：

下载 https://cdn.weread.qq.com/skills/weread-skills.zip 安装 skill

方式二：手动安装

mkdir -p ~/.claude/skills/weread
cd ~/.claude/skills/weread
curl -sL "https://cdn.weread.qq.com/skills/weread-skills.zip" -o /tmp/weread-skills.zip
unzip -o /tmp/weread-skills.zip -d /tmp/weread-skills-extracted
cp /tmp/weread-skills-extracted/weread-skills/*.md .

配置 API Key

API Key 用于连接你的微信读书账号，数据仅你可见。

1. 登录微信读书获取 API Key：https://weread.qq.com
2. 设置环境变量：

export WEREAD_API_KEY=<你的apikey>

API Key 格式为 wrk-xxxxxxxx，绑定用户身份（vid），需要用户身份的接口会自动注入，无需手动传 vid。

五、创建详细过程

第 1 步：创建目录结构

mkdir -p ~/.claude/skills/weread

最终结构：

~/.claude/skills/weread/
├── SKILL.md          # 入口文件（能力列表 + 接口规范 + 通用规则）
├── search.md         # 搜索书籍接口文档
├── book.md           # 书籍信息与阅读进度
├── shelf.md          # 书架管理
├── notes.md          # 笔记/划线
├── review.md         # 书籍点评
├── readdata.md       # 阅读统计
├── profile.md        # 用户信息与阅读统计
└── discover.md       # 发现推荐好书

第 2 步：编写 SKILL.md

这是 Skill 的核心入口文件，包含：

1. 元信息 — name、description、version
2. 能力矩阵 — 所有能力的概览表，每种能力指向对应的参考文档
3. 接口调用规范 — 统一入口、鉴权、请求格式、通用规则
4. 深度链接 — URL Schema 格式，用于在微信读书 App 中打开对应内容

第 3 步：编写各能力参考文档

第 4 步：迭代优化

根据实际使用中的问题进行优化：

六、深度链接（URL Schema）

在展示内容时，拼接跳转链接方便用户在微信读书 App 中打开：

打开书籍

weread://reading?bId={bookId}

跳转到指定章节

weread://reading?bId={bookId}&chapterUid={chapterUid}

跳转到划线/想法位置

weread://bestbookmark?bookId={bookId}&chapterUid={chapterUid}&rangeStart={rangeStart}&rangeEnd={rangeEnd}&userVid={userVid}

range 解析：划线接口返回的 range 格式为 "起始-结束"（如 "900-2004"），拆分后分别填入 rangeStart 和 rangeEnd。

七、常见陷阱与最佳实践

1. 参数不要嵌套

正确（参数平铺在 body 顶层）：

{"api_name":"/user/notebooks","count":100,"skill_version":"1.0.5"}

正确（下一页继续平铺 lastSort）：

{"api_name":"/user/notebooks","count":100,"lastSort":1516907353,"skill_version":"1.0.5"}

错误（不要包在 params 里，会导致分页失效）：

{"api_name":"/user/notebooks","params":{"count":100,"lastSort":1516907353},"skill_version":"1.0.5"}

错误（不要使用 offset/limit，这些字段不是分页参数）：

{"api_name":"/user/notebooks","offset":20,"limit":20,"skill_version":"1.0.5"}

2. 书架数量必须包含专辑

书架总数 = books.length + albums.length + (mp 非空 ? 1 : 0)

• albums[] 是专辑/有声书，也属于书架里的书
• 不要只用 books.length 回答"书架里有多少本书"

正确示例（10 本电子书 + 3 个有声书）：

你的书架共有 13 个条目：10 本电子书 + 3 个专辑/有声书。

错误示例：

你的书架共有 10 本书，另外还有 3 个有声书。
（错误原因：专辑/有声书也在书架里，必须计入总数）

3. 搜索 scope 选择指引

4. 阅读时长单位是秒

totalReadTime、dayAverageReadTime 等字段单位均为秒，展示时转为"X小时Y分钟"格式。

跨年区间查询示例："2024 年 1 月 31 日至今，我的总阅读时长是多少？"

• 推荐做法：查询 2024 至当前年份的 annually，累加年度 totalReadTime；再查询 2024-01 的 monthly，从总和中扣除 2024 年 1 月的 totalReadTime，得到近似的 2024-02-01 至今 口径。

5. progress 是百分比整数

book.getprogress 返回的 progress 范围是 0-100，1 表示 1%（不是 100%）。只有 100 才代表读完。

6. 笔记数 = 书签 + 划线 + 想法

/user/notebooks 的总笔记数 = reviewCount + noteCount + bookmarkCount。不要把 noteCount 单独当作总笔记数。

• noteCount 字段名容易误读：它不是单本书总笔记数，而是划线/高亮原文条数
• reviewCount 已包含个人点评/书评想法，计算总笔记数时不要再额外加"点评数"
• 内容导出 = 划线内容 + 想法/点评内容；当前不能导出书签内容

八、使用方式

# 手动调用
/weread

# 自动触发
# 说 "帮我看看微信读书里的笔记" 即可
# 说 "搜一下三体" 即可
# 说 "我这个月读了多久" 即可

九、文件内容

Skill 已安装至 ~/.claude/skills/weread/ 目录，完整文件请查看：

十、相关资源

• 微信读书 Skill 官方页面: https://weread.qq.com/r/weread-skills
• 微信读书 API Key 获取: https://weread.qq.com
• Skill 下载包: https://cdn.weread.qq.com/skills/weread-skills.zip
• Claude Code 官方文档: https://docs.anthropic.com/en/docs/claude-code
• 微信读书 Agent API Gateway: https://i.weread.qq.com/api/agent/gateway
• MCP 协议: https://modelcontextprotocol.io
• 用户协议: https://weread.qq.com/web/copyright
• 隐私政策: https://privacy.qq.com/mb/policy/tencent-privacypolicy