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

soia-pkm-reading-plan

Office & productivity

View repository

Updated 10-16 09:52

About this skill

soia-pkm-reading-plan

Belongs to the SOIA personal knowledge management domain (soia-pkm-*)'s "processing" stage, in the same family as soia-pkm-forge(output),soia-pkm-bootstrap-vault-base(setup).

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

Customer-readable description

What this skill can do

Scenario-based reading plan generator. Organize a batch of books (from article reading lists, viewpoint mappings, or themes) into an executable reading plan with tables, scheduled by actual word count, and land 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 this article's reading list...

What the customer wants What the skill will do What the customer can see
Complete the work covered by this skill Read the user request, necessary context, and this skill's body workflow, and execute the minimal reliable steps The customer will see Obsidian/vault file changes, terminal logs, generated artifact paths, and the final receipt.
Missing dependencies, permissions, configuration, or key Stop actions that require external state, and clearly state what is missing Install commands, application addresses, configuration paths, or questions that need customer 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 customer uses it

  1. State the goal in natural language, and provide the necessary inputs: files, URLs, repos, workspace, proposal, vault, or platform account status.
  2. The Agent first determines whether this skill is triggered, then checks dependencies, configuration, permissions, and risky actions.
  3. For actions that can be dry-run or previewed, give a preview first; for actions involving deletion, overwriting, sending, publishing, or writing remote state, ask for customer confirmation first.
  4. After execution, verify the real output; do not substitute "looks successful" for evidence.
  5. The final reply must give the customer a visible summary: what was done, log summary, file changes, issues, and next steps.

Dependencies and installation

Install this skill (single skill):

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

Configuration conventions:

~/.config/soia-skills/soia-open-skills/soia-pkm/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 API keys, cookies, sessions, provider home, or local paths are needed, they 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 body, or logs.
  • Strong dependencies, optional dependencies, and third-party skill relationships must be based on this SKILL.md and the subsequent "dependencies / prerequisites / resources / boundaries" description; if it is not clearly written, first add the description or ask the customer, and do not guess.
  • Third-party skills may only declare dependencies and installation methods, and must not directly modify third-party skill files.

Logs and completion receipt

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

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

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

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

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

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

Positioning and Dependencies

Layer Who Relationship
This skill reading-planner Organization and execution of the plan
Data layer (optional enhancement) weread-skills (Tencent/WeChatReading) Get real word counts, ratings, bookshelf, progress; it can still run without them (volume is instead estimated using public publishing information)
Methodology layer (optional reuse) huashu-weread-advisor (alchaincyf/huashu-weread) If already 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 Has no operational relationship with reading plan generation

Design principle:depend on declarations rather than modifying code. Third-party skills update with upstream, and directly modifying their files will be overwritten.

This skill has no hard dependency on third-party skills. When weread-skills or WEREAD_API_KEY is missing, it can only degrade to estimated word counts/public ratings/manual user confirmation; when huashu-weread-advisor is missing, it simply does not reuse its advisor 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 Sort + phase into stages + schedule by word count + cross-compare with the user's existing collection
B · Idea Mapping An article that discusses ideas but does not list books (competency framework/methodology) Break the ideas into items, map each item to books (prioritizing the user's existing collection), then organize according to Mode A
C · Theme A direction (e.g., "intro to investing") First assess the user's level (if huashu-weread-advisor is installed, its path level logic may be borrowed), then organize into a plan

Core Method

1. Pace is calculated by word count, not by guessing based on number of books

"X books a month" will almost inevitably fail for office workers. The correct approach:

  1. Get the real word count of each book: WeRead /book/chapterinfo returns each chapter's wordCount, and summing them all gives the whole book's word count (/book/info does not contain a word count field, do not use the wrong interface).
  2. Explicit assumptions, adjustable by the user: by default "weekdays 30 minutes/day + weekends 60 minutes/day ≈ 4.5 hours per week; reading speed 350 words/minute ≈ 90,000 words per week". Put 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 ÷ words per week, and for difficult books (philosophy/theory) relax this by an additional 30%.
  4. When scheduling, it is better to extend the timeline than to falsely report. 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 WeRead rating (/book/info 's newRating + newRatingDetail.title）：

  • ≥ 80% (widely read/highly acclaimed/masterpiece) → confidently include
  • 70–80% (worth reading) → include normally
  • < 70% (mixed reviews) or insufficient ratings → mark as questionable, show it to the user, and suggest alternatives
  • At the same time cross-reference the user's own data: books with existing notes/highlights show that the user has really read them and has feelings about them, so prioritize them

3. Cross-check against the user's existing book collection (don't let the user buy duplicates)

For each candidate book, verify its current status (actually check, don't guess from the title):

Current status How to mark it in the plan
Finished reading ✅ Skip or mark as "re-read"
Currently reading with progress "Continue reading", put it first
In the library but untouched Main candidate
Not available Check whether it's available on WeRead; if not, provide legal alternative paths (buy the physical book / library),don't recommend pirated copies

4. Output as a table, intuitive first

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

| # | 阶段 | 书名 | 作者 | 字数 | 预计用时 | 排期 | 状态 |
|---|------|------|------|------|---------|------|------|
| 1 | 一·打底 | [[系统之美]] | 德内拉·梅多斯 | 13.7万 | 1.5 周 | 7月上 | ⬜ |
  • Link the book title with [[wikilink]] to the reading record / book card
  • Use a stage column instead of multi-level headings, see the whole picture in one table
  • 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 are synced in using sync_xxx.py "
  • ✅ "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 characters; at your pace of Z hours per week, estimated to finish in W months, scheduled through [year-month]. Do you 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 to the reading plan directory under $OBSIDIAN_VAULT (default 阅读记录/阅读计划/, can be adjusted 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 preferentially reads --vault <vault路径>, the process environment, or a private config.yml. Optional variable names include OBSIDIAN_VAULT and WEREAD_API_KEY; do not write actual values into the open-source skill, the vault body, or shell startup files.

Exception handling

Scenario Handling
Book can't be found on WeRead Mark as "not included", estimate the character 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 character count / rating verification, use estimated values and mark them all as "approx."

Completion receipt

After execution,mustoutput to the user (don't do it silently):

  1. What was done — summarize the completed work in one sentence.
  2. File changes — list the files created / modified / moved (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).