Coding

calibre-catalog-read

Search and inspect a Calibre catalog, or run a validated, delegated analysis of one text-based book.

What it does

Look up Calibre books by list, search query, or book ID, and view catalog details without changing metadata. For an explicitly requested full-book analysis, it prepares the book input, delegates one book to an isolated reader, validates the returned JSON, and handles completion through the prescribed pipeline. Manga and comic-centric books are excluded from the text-analysis flow.

When to use it

  • Browsing the first 50 catalog entries
  • Searching a Calibre library by query
  • Viewing details for a known book ID
  • Requesting analysis of one text-based book

The skill document

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 --book-id 3 --title "..." --state running node skills/calibre-catalog-read/scripts/handle_completion.mjs --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.

Questions people ask

Can it update a book’s title, authors, tags, or other metadata?
No. It treats IDs and requests to check, show, or view as read-only; explicit metadata edits must be routed to calibre-metadata-apply.
How does one-book analysis work?
After confirming the book ID, it prepares a schema-defined input and delegates full-book reading to one isolated calibre-reader run. The child returns analysis JSON only, which is validated before completion handling.
Does it require me to provide the Calibre server URL first?
Not initially. The wrapper scripts first load workspace settings, .env values, and saved defaults; the URL is requested only if a usable library cannot be resolved.

Related skills

ArXiv Paper Processor

Downloads ArXiv artifacts and produces a full-text-based summary.md for each paper.

116 installs1 stars

openclaw-nextcloud

Manage Nextcloud notes, tasks, calendars, files, contacts, shares, and Deck boards from one JSON CLI.

187 installs9 stars

redbook

Research, analyze, and operate Xiaohongshu content through a JSON-capable CLI.

86 installs2 stars

Data Analysis

Turn uploaded datasets into executed analyses, charts, reports, dashboards, and cleaned files.

113 installs4 stars

Fulcra Context

Read consented personal context through CLI, API, REST, or MCP with bounded scope and privacy checks.

115 installs11 stars

Crypto Research

Research tokens, DeFi protocols, on-chain activity, portfolios, whitepapers, and smart-contract risk.

118 installs8 stars