AGENT SKILL

calibre-catalog-read

Read Calibre catalog data via calibredb over a Content server, and run one-book analysis workflow that writes HTML analysis block back to comments while caching analysis state in SQLite. Use for list/search/id lookups and AI reading pipeline for a selected book.

License 许可
MIT
最近更新
2026-06-07
Stars
★ 0
Forks
1

01 前言 Front Matter

name
calibre-catalog-read
metadata
{ "openclaw": { "requires": { "env": [ "CALIBRE_PASSWORD" ], "bins": [ "node", "uv", "calibredb", "ebook-convert" ] }, "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/**", "~/.config/calibre-catalog-read/auth.json" ], "optionalEnv": [ "CALIBRE_USERNAME" ], "dependsOnSkills": [ "subagent-spawn-command-builder" ], "modifiesRemoteData": [ "calibre:comments-metadata" ] } }
description
Read Calibre catalog data via calibredb over a Content server, and run one-book analysis workflow that writes HTML analysis block back to comments while caching analysis state in SQLite. Use for list/search/id lookups and AI reading pipeline for a selected book.

03 SKILL.md 正文

calibre-catalog-read

Use this skill for:

  • Read-only catalog lookup (list/search/id)
  • One-book AI reading workflow (export -> analyze -> cache -> comments HTML apply)

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
  • Do not assume localhost/127.0.0.1; always pass explicit reachable HOST:PORT.
  • If auth is enabled:
    • Preferred: set in /home/altair/.openclaw/.env
      • CALIBRE_USERNAME=<user>
      • CALIBRE_PASSWORD=<password>
    • Then pass only --password-env CALIBRE_PASSWORD (username auto-loads from env)
    • You can still override with --username <user> explicitly.
    • Optional auth cache file: ~/.config/calibre-catalog-read/auth.json
      • Avoid --save-plain-password unless explicitly requested.

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.

Rules:

  • Use subagent only for heavy analysis generation; keep main agent lightweight and non-blocking.
  • In this environment, Python commands must use uv run python.
  • Use the strict prompt template (references/subagent-analysis.prompt.md) as mandatory base; do not send ad-hoc relaxed read instructions.
  • Keep final DB upsert and Calibre metadata apply in main agent.
  • Process one book per run.
  • Confirm model/thinking/timeout once per session, then reuse; do not hardcode provider-specific model IDs in the skill.
  • Configure callback/announce behavior and rate-limit fallbacks using OpenClaw default model/subagent/fallback settings (not hardcoded in this skill).
  • Exclude manga/comic-centric books from this text pipeline (skip when title/tags indicate manga/comic).
  • If extracted text is too short, stop and ask user for confirmation before continuing.
    • The pipeline returns reason: low_text_requires_confirmation with prompt_en text.

Language policy

  • Do not hardcode user-language prose in pipeline scripts.
  • Generate user-visible analysis text from subagent output, with language controlled by user-selected settings and lang input.
  • Fallback local analysis in scripts is generic/minimal; preferred path is subagent output following the prompt template.

Orchestration note (important)

run_analysis_pipeline.py is a local script and does not call OpenClaw tools by itself. Subagent execution must be orchestrated by the agent layer using sessions_spawn.

Required runtime sequence:

  1. Main agent prepares subagent_input.json + chunked source_files from extracted text.
    • Use:
    node skills/calibre-catalog-read/scripts/prepare_subagent_input.mjs \
      --book-id <id> --title "<title>" --lang ja \
      --text-path /tmp/book_<id>.txt --out-dir /tmp/calibre_subagent_<id>
    
  2. Main agent uses the shared builder skill subagent-spawn-command-builder to generate the sessions_spawn payload, then calls sessions_spawn.
    • Build with profile calibre-read and run-specific analysis task text.
    • Use the generated JSON as-is (or merge minimal run-specific fields such as label/task text).
  3. Subagent reads all source_files and returns analysis JSON (schema-conformant).
  4. Main agent passes that file via --analysis-json to run_analysis_pipeline.py for DB/apply.

If step 2 is skipped, pipeline falls back to local minimal analysis (only for emergency/testing).

Chat execution model (required, strict)

For Discord/chat, always run as two separate turns.

Turn A: start only (must be fast)

  • Select one target book.
  • Build spawn payload with subagent-spawn-command-builder (--profile calibre-read + run-specific --task).
  • Call sessions_spawn using that payload.
  • Record run state (runId) via run_state.mjs upsert.
  • Reply to user with selected title + "running in background".
  • Stop turn here.

Turn B: completion only (separate later turn)

Trigger: completion announce/event for that run.

  • Run one command only (completion handler):
    • scripts/handle_completion.mjs (get -> apply -> remove, and fail on error).
  • If runId is missing, handler returns stale_or_duplicate and does nothing.
  • Send completion/failure reply from handler result.

Hard rule:

  • Never poll/wait/apply in Turn A.
  • Never keep a chat listener turn open waiting for subagent completion.

Run state management (single-file, required)

For one-book-at-a-time operation, keep a single JSON state file:

  • skills/calibre-catalog-read/state/runs.json

Use runId as the primary key (subagent execution id).

Lifecycle:

  1. On spawn acceptance, upsert one record:
    • runId, book_id, title, status: "running", started_at
  2. Do not wait/poll inside the same chat turn.
  3. On completion announce, load record by runId and run apply.
  4. On successful apply, delete that record immediately.
  5. On failure, set status: "failed" + error and keep record for retry/debug.

Rules:

  • Keep this file small and operational (active/failed records only).
  • Ignore duplicate completion events when record is already removed.
  • If record is missing at completion time, report as stale/unknown run and do not apply blindly.

Use helper scripts (avoid ad-hoc env var mistakes):

# Turn A: register running task
node skills/calibre-catalog-read/scripts/run_state.mjs upsert \
  --state skills/calibre-catalog-read/state/runs.json \
  --run-id <RUN_ID> --book-id <BOOK_ID> --title "<TITLE>"

# Turn B: completion handler (preferred)
node skills/calibre-catalog-read/scripts/handle_completion.mjs \
  --state skills/calibre-catalog-read/state/runs.json \
  --run-id <RUN_ID> \
  --analysis-json /tmp/calibre_<BOOK_ID>/analysis.json \
  --with-library "http://HOST:PORT/#LIBRARY_ID" \
  --password-env CALIBRE_PASSWORD --lang ja

04 同仓库更多 Skills

javimosch
javimosch/open-claw-skills

crowd-prompting

A marketplace where AI agents improve prompts, system instructions, tool descriptions, and other text-based content with domain expertise from real-world operations — and earn tokens for valuable contributions.

★ 0
javimosch
javimosch/open-claw-skills

ceaser

Interact with the Ceaser privacy protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- shield, unshield, note management, and protocol queries. All ceaser tool calls use CLI subcommands (npx -y ceaser-mcp <subcommand>). Ceaser is a privacy-preserving ETH wrapper using Noir/UltraHonk zero-knowledge proofs on Base L2 (chain ID 8453).

★ 0
javimosch
javimosch/open-claw-skills

ceaser-send

Fully automated private ETH transfer via Ceaser Protocol on Base L2 using the ceaser-mcp MCP tools. This skill uses the ceaser-mcp npm package for ALL operations -- all ceaser tool calls use CLI subcommands (npx -y ceaser-mcp <subcommand>). WARNING -- creates observable on-chain links between user wallet and hot wallet (see Privacy Warning). Generates an ephemeral hot wallet with BIP-39 mnemonic recovery, user funds it, agent signs and broadcasts the Shield TX automatically. Exactly one manual step required (funding the hot wallet with ETH). Uses Noir/UltraHonk zero-knowledge proofs.

★ 0
javimosch
javimosch/open-claw-skills

dilemm-ai

Compete in DilemmAI, the prisoner's dilemma AI arena at dilemm.ai. Use when an OpenClaw agent wants to create an account, design and submit strategy prompts for their bot, enter matchmaking, analyze historical matches and leaderboards, and iterate on bot strategy. Requires headless browser automation (no API available yet).

★ 0
javimosch
javimosch/open-claw-skills

moldium

Post and manage content on the Moldium blog platform. Triggered by "post to Moldium", "write a blog post", "publish an article", etc.

★ 0
javimosch
javimosch/open-claw-skills

arxiv-paper-reviews

Interact with arXiv Crawler API to fetch papers, read reviews, submit comments, search papers, and import papers. Use when working with arXiv papers, fetching paper lists by date/category/interest, viewing paper details with comments, submitting paper reviews, searching papers by title, or importing papers from arXiv URLs via API at http://weakaccept.top:8000/.

★ 0