SuperAPI AI Directory
Partner中文AI newsFavorites
Skillssoia-pkm-reading-plan

soia-pkm-reading-plan

Office & productivity

View repository

Updated 10-16 08:46

About this skill

soia-pkm-reading-plan

Belongs to the "processing" stage of the SOIA personal knowledge management domain (soia-pkm-*), in the same family as soia-pkm-bootstrap-vault-base(building).

Turn "a batch of books I want to read" into a plan that "fits into the schedule and can be finished".

Client-readable description

What this skill can do

Scenario-based reading plan generator. Organize a batch of books (from an article book list, viewpoint map, or topic) into an executable reading plan with a table, scheduled by real word count, and save it as an Obsidian note. Optionally use weread-skills to enhance word count/rating/bookshelf verification, and fall back to estimation when unavailable; optionally reference the huashu-weread-advisor methodology but do not depend on it. When the user says "make a reading plan", "schedule a plan by XX scenario", "schedule the book list from this article...

What the client wants What the skill will do What the client can see
Complete the work covered by this skill Read the user request, necessary context, and this skill's main workflow, and execute the minimum reliable steps The client will see Obsidian/vault file changes, terminal logs, generated artifact paths, and a final receipt.
Missing dependencies, permissions, configuration, or key Stop actions that require external state, and clearly state what is missing Install command, application address, configuration path, or question requiring client confirmation
Execution complete Summarize successes, skips, failures, file changes, and verification results A completion receipt that can be copied into a ticket/log

How the client uses it

  1. State the goal in natural language and provide the necessary inputs: files, URL, repo, workspace, proposal, vault, or platform account status.
  2. For actions that can be dry-run or previewed, give a preview first; for deletions, overwrites, sends, publications, or writes to remote state, ask for client confirmation first.

Dependencies and installation

Installation (recommended: install the entire domain plugin, installing all skills in this repository at once):

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-pkm-vault@soia

When you only want this one skill, you can use the npx route. Note that the skill will land in the shared source of truth ~/.agents/skills; if the plugin is also installed, the same skill will appear in two indexes and each will drift, so it is recommended to choose one of the two:

npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-reading-plan -y

Configuration conventions:

~/.config/soia-skills/soia-pkm-reading-plan/config.yml
SOIA_PKM_READING_PLAN_CONFIG_FILE=<custom-config-path>
  • If this skill does not need private configuration, you may skip creating config.yml。
  • If an API key, cookie, session, provider home, or local path is needed, it can only go into private config.yml, the process environment, or the provider's own login state, and must not be written into the repository, vault text, or logs.
  • Third-party skills can only declare dependencies and installation methods, and must not directly modify third-party skill files.

WorkBuddy 's loading unit is role-based experts rather than plugins,npx skills add -a '*' cannot cover it, so it needs to be installed separately, see docs/install/workbuddy.md。

Logs and completion receipt

Every execution must let the client see the process and results. Minimum receipt format:

完成：<一句话说明本次完成了什么>。

日志摘要：
- started: <检查到的输入/配置/依赖，不打印秘密值>
- processed: <数量或范围>
- created/updated: <数量或路径>
- skipped/failed: <数量和原因>

文件变化：
- <绝对路径或“未改动文件”>

验证：
- <运行过的检查、命令或人工核对点>

问题与下一步：
- <缺 key / 缺依赖 / 需要客户确认 / 建议下一条命令；没有则写“无”>

Positioning and dependencies

Layer Who it is Relationship
This skill reading-planner Organization and implementation of the plan
Data layer (optional enhancement) weread-skills (Tencent/WeChatReading) Use real word counts, ratings, bookshelf, and progress; it can also run without them (fall back to estimating length using public publishing information)
Methodology layer (optional reuse) huashu-weread-advisor (alchaincyf/huashu-weread) If installed, the book selection/recommendation step follows its "bookshelf + notes cross-analysis" methodology and checkpoint principles; this skill does not modify any of its files
Non-dependency book-to-skill / find-skills No runtime relationship with reading plan generation

Design principles:Declare dependencies rather than modify code. Third-party skills update with upstream, and directly editing their files will be overwritten.

This skill has no hard dependency on third-party skills. When missing weread-skills or WEREAD_API_KEY , it can only degrade to estimated word counts/public ratings/manual user confirmation; when missing huashu-weread-advisor , it simply does not reuse their advisory methodology, and can still independently generate a reading plan.

Three input modes

Mode Input Task
A · External book list An article / ready-made book list Ranking + phased stages + scheduling by word count + cross-check with the user's existing collection
B · Viewpoint mapping An article that argues ideas but does not list books (capability framework/methodology) Break the viewpoints into items, map each item to books (prioritizing the user's existing collection), then organize according to Mode A
C · Topic A direction (e.g. "Introduction to Investing") First determine the user's level (if huashu-weread-advisor is installed, its path level logic can be borrowed), then organize it into a plan

Core method

1. Pace is calculated by word count, not guessed by number of books

"X books a month" is almost bound to fail for office workers. The correct approach:

  1. Get the real word count of each book: WeChat Read /book/chapterinfo returns each chapter's wordCount, and summing them all gives the whole book's word count (/book/info does not include a word count field, so do not use the wrong API).
  2. Explicit assumptions, adjustable by the user: default "weekdays 30 minutes/day + weekends 60 minutes/day ≈ 4.5 hours per week; reading speed 350 words/minute ≈ 90,000 words per week". Write the assumptions at the top of the plan, and tell the user, "If you want to change the pace, just say so, and the AI will reschedule."
  3. Estimated time per book = word count ÷ weekly word count, and for hard books (philosophy/theory), relax this by another 30%.
  4. It is better to stretch the schedule longer than to falsely report it. If the total exceeds half a year, honestly schedule it into next year.

2. Book lists must be verified with objective data, not just impressions

For each candidate book, pull the WeChat Read rating (/book/info 's newRating + newRatingDetail.title）：

  • ≥ 80% (widely praised/highly acclaimed/masterpiece) → safely schedule it
  • 70–80% (worth reading) → schedule normally
  • < 70% (mixed reviews) or insufficient ratings → mark as questionable, show it to the user, and suggest alternatives
  • Also cross-check the user's own data: books with existing notes/highlights show the user really read them and had feelings about them, so prioritize them

3. Cross-check with the user's existing collection (do not make the user buy duplicates)

Check the current status of each candidate book (actually look it up, do not guess from the title):

Current status How to mark it in the plan
Already finished ✅ Skip or mark as "reread"
In-progress with progress "Continue reading", ranked first
In the library but untouched Main candidates
None Check whether it's available on WeRead; if not, provide legal alternatives (buy physical copy/library),Don't recommend pirated copies

4. Output as a table, visual clarity first

The main body of the plan is one large table (checkboxes at the start of the row for easy ticking):

| # | 阶段 | 书名 | 作者 | 字数 | 预计用时 | 排期 | 状态 |
|---|------|------|------|------|---------|------|------|
| 1 | 一·打底 | [[系统之美]] | 德内拉·梅多斯 | 13.7万 | 1.5 周 | 7月上 | ⬜ |
  • Book titles use [[wikilink]] linked to reading records/book cards
  • Stage columns replace multi-level headings, one table shows the whole picture
  • Below the table, give a paragraph on "why this order" + assumed parameters + how to adjust

5. Write a plan for humans to read, don't expose technical details

The plan file is aimed at "users who are reading", not engineers:

  • ❌ "Highlights use sync_xxx.py synced in"
  • ✅ "After finishing, tell the AI 'sync this book's highlights', and the notes will automatically go into the reading record"

Script names and API names stay only in this SKILL.md, and do not appear in the produced plan.

Checkpoint (must pass user confirmation before writing to disk)

Before writing the file, show the user the three key elements:

Scenario "X", N books selected (M of which you already have), total about Y words; at your pace of Z hours per week, estimated to finish in W months, scheduled through [year-month]. Want to add or remove books, change the pace, or change the scenario name?

List uncertain books (low ratings/uncertain mapping) separately for the user to decide.

Output location and frontmatter

Write into $OBSIDIAN_VAULT under the reading plan directory (default 阅读记录/阅读计划/, adjustable according to the user's vault structure):

<YYYY-MM-DD>-<场景名>.md

---
tags: [阅读计划]
title: <场景名>
scenario: <场景分类>
book_count: <n>
total_words: <总字数，万字>
pace: <每周字数假设>
created: <YYYY-MM-DD>
source: "[[<来源文章>]]"   # 模式 A/B 才有
---

Environment variables

The script reads --vault <vault路径>, process environment, or private config.yml first. Optional variable names include OBSIDIAN_VAULT and WEREAD_API_KEY; do not write actual values into open-source skills, vault body text, or shell startup files.

Exception handling

Scenario Handling
Book can't be found on WeRead Mark as "not included", estimate word count using public publication information and note "approx."
Multiple suspected matches for the book title List them for the user to confirm, don't guess
More than 15 candidates Suggest splitting into two scenario plans
No WEREAD_API_KEY Skip word count/rating verification, use estimated values and mark all as "approx."

Completion receipt

The receipt includes:

  1. What was done — a one-sentence summary of the completed work.
  2. File changes — list newly created / modified / moved files (full paths); if no files were changed, state "no files changed".
  3. Next steps — optional follow-up suggestions (such as the next skill to connect to).