--- name: calibre-catalog-read description: Read-only Calibre catalog lookup (including ID-based read-only lookups like "ID 1021 を確認して") and one-book analysis-comments workflow over a running Content server. Use for any list/search/id viewing even when a specific ID is mentioned. Never for title/authors/tags/series/series_index metadata edits. metadata: {"openclaw":{"requires":{"bins":["node","uv","calibredb","ebook-convert"],"env":["CALIBRE_PASSWORD"]},"optionalEnv":["CALIBRE_USERNAME"],"primaryEnv":"CALIBRE_PASSWORD","dependsOnSkills":["subagent-spawn-command-builder"],"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 this skill for:

• Read-only catalog lookup (list/search/id)
• ID-based read-only lookups: "ID 1021 を確認して", "1021番の詳細", "show me book 1021", "ID 1021 の情報を見せて"
• One-book AI reading workflow (export -> analyze -> cache -> comments HTML apply)
• Natural conversational book-reference turns where a lightweight read-only lookup would improve the reply

- Examples: the user mentions a book that may exist in the library, suggests "if you're interested, read it", asks whether it is in the library, or continues a reading-related conversation without using explicit command wording

Skill selection contract (strict)

• This skill is read-only for catalog lookup + analysis workflow.
• This skill may also be selected from natural conversation when the likely user need is a lightweight library check or book lookup, even if the user does not use explicit command-style wording.
• In such conversational cases, prefer the smallest useful action first:

- first choice: id/search/list style read-only lookup - do not jump directly into heavy analysis unless the user clearly asks for it - do not treat casual book talk as metadata-edit intent

• If user intent includes metadata edit/fix/update (title/authors/series/series_index/tags/publisher/pubdate/languages),

route to calibre-metadata-apply and do not execute edit paths here.

Do NOT use this skill for:

• Editing title/authors/series/series_index/tags/publisher/pubdate/languages
• Any user request that says "metadata edit", "title fix", "ID指定で編集"
• Heavy one-book analysis when the user only made a casual conversational reference and did not ask for reading/analysis
• Those must use calibre-metadata-apply

Routing: ID in request ≠ edit intent

• ID が含まれるリクエストはデフォルトで読み取り専用 → このスキル
• calibre-metadata-apply へのルーティングは明示的な編集動詞がある場合のみ (修正/編集/変更/直す/fix/edit/update/change)
• 確認/見せて/教えて/詳細/check/show/view は読み取り → このスキル

Requirements

• calibredb available on PATH in the runtime where scripts are executed.
• ebook-convert available for text extraction.
• subagent-spawn-command-builder installed (for spawn payload generation).
• Reachable Calibre Content server URL in --with-library format:

- http://HOST:PORT/#LIBRARY_ID - If LIBRARY_ID is unknown, use #- once to list available IDs on the server.

• Do not assume localhost/127.0.0.1; always pass explicit reachable HOST:PORT.
• --with-library can be omitted only when one of these is configured:

- env: CALIBRE_WITH_LIBRARY or CALIBRE_LIBRARY_URL or CALIBRE_CONTENT_SERVER_URL - optional library id completion: CALIBRE_LIBRARY_ID

• Read the "Calibre Content Server" section of TOOLS.md for the correct --with-library URL.
• Host failover (IP change resilience):

- Optional env: CALIBRE_SERVER_HOSTS=host1,host2,... - Script auto-tries candidates, including WSL host-side nameserver from /etc/resolv.conf.

• If auth is enabled:

- Preferred: set in /home/altair/.openclaw/.env - CALIBRE_USERNAME= - CALIBRE_PASSWORD= - Auth scheme policy for this workflow: - Non-SSL deployment assumes Digest authentication. - Do not pass auth mode arguments such as --auth-mode / --auth-scheme. - Then pass only --password-env CALIBRE_PASSWORD (username auto-loads from env) - You can still override with --username explicitly.

Commands

List books (JSON):

node skills/calibre-catalog-read/scripts/calibredb_read.mjs list \
  --with-library "http://192.168.11.20:8080/#Calibreライブラリ" \
  --password-env CALIBRE_PASSWORD \
  --limit 50

Search books (JSON):

node skills/calibre-catalog-read/scripts/calibredb_read.mjs search \
  --with-library "http://192.168.11.20:8080/#Calibreライブラリ" \
  --password-env CALIBRE_PASSWORD \
  --query 'series:"中公文庫"'

Get one book by id (JSON):

node skills/calibre-catalog-read/scripts/calibredb_read.mjs id \
  --with-library "http://192.168.11.20:8080/#Calibreライブラリ" \
  --password-env CALIBRE_PASSWORD \
  --book-id 3

Run one-book pipeline (analyze + comments HTML apply + cache):

uv run python skills/calibre-catalog-read/scripts/run_analysis_pipeline.py \
  --with-library "http://192.168.11.20:8080/#Calibreライブラリ" \
  --password-env CALIBRE_PASSWORD \
  --book-id 3 --lang ja

Cache DB

Initialize DB schema:

uv run python skills/calibre-catalog-read/scripts/analysis_db.py init \
  --db skills/calibre-catalog-read/state/calibre_analysis.sqlite

Check current hash state:

uv run python skills/calibre-catalog-read/scripts/analysis_db.py status \
  --db skills/calibre-catalog-read/state/calibre_analysis.sqlite \
  --book-id 3 --format EPUB

Main vs Subagent responsibility (strict split)

Use this split to avoid long blocking turns on chat listeners.

Main agent (fast control plane)

• Validate user intent and target book_id.
• Confirm subagent runtime knobs: model, thinking, runTimeoutSeconds.
• Start subagent and return a short progress reply quickly.
• After subagent result arrives, run DB upsert + Calibre apply.
• Report final result to user.

Subagent (heavy analysis plane)

• Read extracted source payload.
• Generate analysis JSON strictly by schema.
• Do not run metadata apply or user-facing channel actions.

Never do in main when avoidable

• Long-form content analysis generation.
• Multi-step heavy reasoning over full excerpts.

Turn policy

• One book per run.
• Prefer asynchronous flow: quick ack first, final result after analysis.
• If analysis is unavailable, either ask user or use fallback only when explicitly acceptable.

Subagent pre-flight (required)

Before first subagent run in a session, confirm once:

• model
• thinking (low/medium/high)
• runTimeoutSeconds

Do not ask on every run. Reuse the confirmed settings for subsequent books in the same session unless the user asks to change them.

Subagent support (model-agnostic)

Book-reading analysis is a heavy task. Use a subagent with a lightweight model for analysis generation, then return results to main agent for cache/apply steps.

• Prompt template: references/subagent-analysis.prompt.md
• Input schema: references/subagent-input.schema.json
• Output schema: references/subagent-analysis.schema.json
• Input preparation helper: scripts/prepare_subagent_input.mjs

- Splits extracted text into multiple files to avoid read-tool single-line size issues.

...