calibre-catalog-read

name	calibre-catalog-read
description	Calibre catalog lookup, viewing, and delegated one-book analysis.
metadata	{"openclaw":{"requires":{"bins":["node","uv","calibredb","ebook-convert"],"env":["CALIBRE_PASSWORD"]},"optionalEnv":["CALIBRE_USERNAME"],"primaryEnv":"CALIBRE_PASSWORD","localWrites":["skills/calibre-catalog-read/state/runs.json","skills/calibre-catalog-read/state/calibre_analysis.sqlite","skills/calibre-catalog-read/state/cache/**"],"modifiesRemoteData":["calibre:comments-metadata"]}}

calibre-catalog-read

Use for Calibre read-only catalog work and the one-book analysis/comments workflow.

Routing

Use this skill for:

• list/search/id catalog lookup.
• ID viewing: ID 1021 を確認して, 1021番の詳細, show/view/check book 1021.
• Natural book conversation where a lightweight library lookup helps.
• One-book analysis only when the user clearly asks to read/analyze a book.

Do not use for metadata edits. If the user asks to change title/authors/series/series_index/tags/publisher/pubdate/languages, route to calibre-metadata-apply.

ID alone is not edit intent. 確認/見せて/教えて/詳細/check/show/view means read-only. calibre-metadata-apply requires explicit edit verbs such as 修正/編集/変更/直す/fix/edit/update/change.

Local Facts

Read the workspace AGENTS.md ## Tools section for Content server URL, library id, auth policy, and reading script.

Connection bootstrap:

• Do not ask the user for --with-library first.
• First try scripts without explicit --with-library; they auto-load .env and saved defaults.
• Ask for URL only if resolution fails (missing --with-library or unable to resolve usable library).
• Non-SSL auth is Digest; do not pass auth-mode/auth-scheme flags.
• Never start calibre-server from chat.
• Do not assume localhost/127.0.0.1; the workspace AGENTS.md ## Tools section has the reachable server.

Requirements: calibredb, ebook-convert, node, and uv.

Commands

Prefer wrapper scripts over direct calibredb in agent/chat.

List: node skills/calibre-catalog-read/scripts/calibredb_read.mjs list --password-env CALIBRE_PASSWORD --limit 50

Search: node skills/calibre-catalog-read/scripts/calibredb_read.mjs search --password-env CALIBRE_PASSWORD --query 'series:"中公文庫"'

Get by id: node skills/calibre-catalog-read/scripts/calibredb_read.mjs id --password-env CALIBRE_PASSWORD --book-id 3

One-book pipeline with prepared analysis JSON: uv run python skills/calibre-catalog-read/scripts/run_analysis_pipeline.py --password-env CALIBRE_PASSWORD --book-id 3 --lang ja --analysis-json /tmp/calibre_3/analysis.json

Prepare subagent input: node skills/calibre-catalog-read/scripts/prepare_subagent_input.mjs --book-id 3 --lang ja --out-dir /tmp/calibre_3

Run state: node skills/calibre-catalog-read/scripts/run_state.mjs upsert --run-id <RUN_ID> --book-id 3 --title "..." --state running node skills/calibre-catalog-read/scripts/handle_completion.mjs --run-id <RUN_ID> --analysis-json /tmp/analysis.json

One-Book Analysis Flow

Delegate only full-book reading. Main remains the control plane.

1. Confirm target book_id.
2. Prepare input with scripts/prepare_subagent_input.mjs.
3. Build a self-contained task from references/subagent-analysis.prompt.md and the generated subagent_input.json path.
4. Call OpenClaw sessions_spawn with the live tool schema:
   • runtime: "subagent"
   • agentId: "calibre-reader"
   • mode: "run"
   • context: "isolated"
   • lightContext: true
   • omit model and thinking; the target agent profile owns them.
5. Save the returned run/session identifiers with scripts/run_state.mjs upsert.
6. Use sessions_yield when completion belongs in a later turn. Do not poll session or subagent lists.
7. On completion, validate the raw JSON against references/subagent-analysis.schema.json, then run scripts/handle_completion.mjs.

Use Swarm only for an explicitly requested independent multi-book batch. Keep one book per child and preserve the same input/output contract.

Hard rules:

• One book per child run.
• Main owns user-facing replies and Calibre comments apply.
• Child reads prepared input and emits analysis JSON only; it must not apply metadata or message the user.
• Use references/subagent-analysis.prompt.md; do not send relaxed ad-hoc instructions.
• Input schema: references/subagent-input.schema.json; output schema: references/subagent-analysis.schema.json.
• Exclude manga/comic-centric books from this text pipeline.
• If extracted text is too short, stop and ask for confirmation.
• Keep state/runs.json to active/failed records only.
• At completion, missing runId means stale/duplicate; do not apply blindly.

Cache And Language

Cache DB is skills/calibre-catalog-read/state/calibre_analysis.sqlite. Treat cache as acceleration, not authority; final user-visible analysis must reflect the current target and completed run.

Language policy:

• Do not hardcode user-language prose in pipeline scripts.
• Generate user-visible analysis from child output, controlled by user settings and the lang input.
• Local fallback analysis is generic/minimal; prefer output following the prompt template.