soia-pkm-library-book-catalog

The local catalog layer of the PKM library: it only reads and writes Markdown and YAML frontmatter within the vault, backfills missing to-read records, and generates three overviews that can be browsed in Obsidian. It does not call the WeRead API, does not require a third-party skill, and will not stop due to missing WeRead configuration.

Customer-readable description

What this skill can do

This skill is suitable for organizing a local library based on existing book cards or reading records. It generates a library overview and a reading log overview according to the classification field of the book cards. It can also idempotently backfill books that "have a book card but no reading record" as "to-read" records, and generate a view grouped by type.

Customer wants	Skill will do	Customer can see
Backfill to-read records	Scan book cards and reading records, create missing records, skip if the target already exists	Counts of created, skipped, and failed
Regenerate library overview	Read local book cards and generate a category-nested view	Output files and bibliographic statistics
Update reading log overview	Summarize the 7-state reading lifecycle based on book card classification	Status, classification, and processing statistics
Library organization	Execute backfill and the three view generations in sequence	Receipt for each stage and repeatable execution results

How customers use it

Use natural language to state that you want to backfill to-read records, update a certain overview, or organize the entire library.
Provide --vault <path>, or set OBSIDIAN_VAULTin the private configuration; neither WEREAD_API_KEY nor a WeRead login state is required.
The generation script supports --output <path> preview; after confirming the content, omit this parameter to write back to the vault.
After execution, verify the actual output and statistics; all scripts can be safely run repeatedly.

Dependencies and installation

Install this skill:

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

claude plugin install soia-pkm-vault@soia

When only this one skill is needed, the npx route can be used. Note that the skill will fall into the shared source of truth ~/.agents/skills; if a plugin is also installed, the same skill will appear as 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-library-book-catalog -y

The runtime dependency is only Python 3 and Markdown files in the local vault; it does not depend on WeRead,weread-skills、WEREAD_API_KEY, the network, or additional pip packages.

Private configuration path:

~/.config/soia-skills/soia-pkm-library-book-catalog/config.yml
SOIA_PKM_LIBRARY_BOOK_CATALOG_CONFIG_FILE=<custom-config-path>
SOIA_PKM_LIBRARY_BOOK_CATALOG_ENV_FILE=<compat-config-path>

Example:

env:
  OBSIDIAN_VAULT: "<vault-path>"

For compatibility with older calling methods, the script also accepts SOIA_PKM_LIBRARY_CONFIG_FILE and SOIA_PKM_LIBRARY_ENV_FILE; new configurations should preferentially use the catalog-specific names above. The configuration only stores local paths and does not commit private data.

WorkBuddy The loading unit of is a role-based expert rather than a plugin,npx skills add -a '*' does not cover it, and it needs to be installed separately, see docs/install/workbuddy.md。

Logs and completion receipt

Each run will output the scan scope, counts of created/updated/skipped/failed, output categories, and next-step suggestions. Logs involving the vault only report generalized locations and resource categories, and do not print keys or unnecessary local absolute paths. At the end, the actual file changes and verification method must be stated.

What it can do

Script	Function	When to run
`backfill_reading_records.py`	Batch-create "to-read" records for books that have a book card but no reading record	When you want to align book cards with reading records
`gen_library_md.py`	Generate a library overview by primary/secondary category	After book cards change
`gen_records_md.py`	Generate a reading record overview by the book card's authoritative category and 7-state status	After reading records change
`gen_genre_library_md.py`	Generate a library overview by single-level type	When you need a type view

How to run

The following commands are executed from this skill's scripts/ directory:

python3 backfill_reading_records.py --vault <vault-path>
python3 gen_library_md.py --vault <vault-path> --output <preview-path>
python3 gen_records_md.py --vault <vault-path> --output <preview-path>
python3 gen_genre_library_md.py --vault <vault-path> --base <vault-book-library-dir> --output <preview-path>

After confirming the preview, remove --output to write back to the vault. All scripts share the following parameterization conventions:

--vault <path> or OBSIDIAN_VAULT: vault root directory, command line takes precedence.
--base <relpath>: the library's path relative to the vault; pass it explicitly according to the actual library, without relying on a fixed personal directory name.
--config <json>: override category, status, icon, or field passthrough settings (supported by specific scripts).
Private configuration is loaded using SOIA_PKM_LIBRARY_BOOK_CATALOG_CONFIG_FILE, a compatible alias, or the default configuration path; it will not override environment variables already present in the process.

Directory contract and upstream relationships

The library directory is determined by --base , and the core structure is:

<base>/
├── 00_图书馆/
│   └── 书目/<分类目录>/<书名>.md
└── 阅读记录/
    ├── 想读/  待读/  计划读/  在读/
    ├── 暂停/  搁置/  完成/
    └── 阅读记录-总览.md

The book card's category/subcategory is the authoritative source for categories; reading records look up book cards via book: "[[书名]]" . Book cards that no record points to are exactly the backfill_reading_records.py objects to be backfilled. The generation scripts read local Markdown and do not request data from remote sources.

soia-pkm-library-weread-sync is an optional upstream: it can first materialize WeRead data into book cards, reading records, and machine sections, and this skill then consumes these local files. catalog can also process existing local data on its own and still run without installing the upstream sync skill.

Write-back and idempotency boundaries

Markdown views are product feature files of the vault, and by default are written back to the library directory located by --base .
The three gen_* scripts support --output <path> preview to avoid directly overwriting overview files.
backfill_reading_records.py only creates when the target record does not exist; existing files are skipped and user records are not overwritten.
The scripts do not create network caches, do not write external state, and do not call providers; the temporary preview path is passed in by the user via --output , and temporary files are managed by the caller.

Boundaries and exceptions

Scenario	Handling
Vault not specified	Exit and prompt to pass `--vault` or set `OBSIDIAN_VAULT`
Library directory does not exist	Output a locatable missing-directory prompt and exit, without fabricating an overview
Target to-read record already exists	Skip, without overwriting existing content
Book card is missing a title or category	Classify by the script's default value and prompt in the log
Local book title cannot be looked up	Skip and print a warning, without interrupting batch organization
Want to confirm the generated content	Use `--output` to output to a temporary preview file

Completion receipt

After completion, you must report: the script and scope of this run, the counts of scanned/created/updated/skipped/failed, the resource categories actually written, the preview or write-back verification results, and any issues that require user handling. Do not treat "the command returned 0" alone as evidence that the content is correct; at minimum, check that the output exists and contains the expected heading or statistics.