Calibre Metadata Apply

Primary skill for Calibre metadata edits (write operations) over a running Content server. Use ONLY when the user explicitly requests changing/editing/fixing...

Security Scan

The skill appears to do what it says (apply Calibre metadata) but has several operational choices that could expose credentials or metadata (auto-loading dotfiles, optional plaintext password saving, ability to pass password on the command line, and optional subagent/model usage) and those warrant caution before installation.

Purpose & Capability

Name/description align with required binaries and behavior: it legitimately requires `calibredb` and Node, and the main declared credential is CALIBRE_PASSWORD. The included scripts implement metadata lookups, dry-run/apply flow, and run-state management consistent with an edit/apply skill.

Instruction Scope

SKILL.md and scripts stick to metadata-edit workflows, but the skill explicitly supports using a subagent for heavy analysis and notes that 'text/metadata sent to subagent can reach model endpoints configured by runtime profile.' That means metadata (and possibly other text) can be forwarded to external model endpoints unless the caller disables subagent processing. The scripts also read local dotfiles (.env in cwd and ~/.openclaw/.env) automatically to hydrate env vars, which may pull unrelated secrets into the process if present. The README/policy allow saving auth and even saving plain passwords if the user requests it—this broadens the data surface beyond the simple 'apply metadata' claim.

Install Mechanism

No external installer or remote download is declared; this is instruction+scripts only. That keeps install risk low because nothing is fetched from arbitrary URLs during install.

Credentials

The registry lists only CALIBRE_PASSWORD as required, which is appropriate, but the code automatically hydrates .env files (process.cwd()/.env and ~/.openclaw/.env) and will set any variables found there. That can unexpectedly import unrelated secrets into the skill's environment. The script also can accept/insert a plaintext password onto calibredb command lines (it builds commands with `--password <value>` if `auth.password` is present) and the README documents optional saving of auth (including a --save-plain-password option). These behaviors increase the chance credentials are exposed (process lists, logs, or config files).

Persistence & Privilege

The skill writes local state at skills/.../state/runs.json (declared) and documents an auth cache at ~/.config/calibre-metadata-apply/auth.json; README explicitly allows saving auth and even plain passwords via `--save-plain-password`. 'always' is false, and the skill does not request system-wide privileges, but the optional persistent storage of credentials (including plaintext) and retained run state are notable persistence/privacy concerns.

What to consider before installing

This skill is functionally coherent for editing Calibre metadata, but review and limit sensitive behaviors before use: - Avoid storing credentials in plaintext. Do not use `--save-plain-password`. Prefer exporting CALIBRE_PASSWORD in the environment and pass via `--password-env CALIBRE_PASSWORD` rather than inline `--password` on the command line. - Be aware the scripts automatically load .env files from the current directory and ~/.openclaw/.env. Remove unrelated secrets from those files (e.g., AWS keys) or run the skill from a clean working directory. - The skill can delegate heavy analysis to a subagent/model. If metadata or book-related text is sensitive, disable subagent orchestration or ensure the configured model endpoints are trusted; otherwise metadata may be sent to external model endpoints. - Inspect or audit the included scripts (calibredb_apply.mjs, run_state.mjs, handle_completion.mjs) in your environment before running. Confirm that you’re comfortable with the local state file location (skills/.../state/runs.json) and the documented auth cache (~/.config/calibre-metadata-apply/auth.json). - Prefer dry-run and explicit user approval before any `--apply`. The skill’s required flow includes a dry-run first; follow that. What would raise confidence to High: a) the author/owner is known and trusted, b) removal or hardening of plaintext password saving and explicit disabling of inline `--password` usage in code, and c) a configurable opt-out that prevents automatic .env hydration and disables subagent/model delegation by default.

A skill for updating metadata of existing Calibre books.

Skill selection contract (strict)

• If the user intent is metadata edit/fix/update, this skill is mandatory.
• If the request mentions an ID together with edit/fix/update intent (e.g. ID1011 タイトル修正, ID1011 のタイトルを直して), this skill is mandatory.
• If the request mentions an ID but only for viewing/checking/confirming (e.g. ID1021 を確認して, ID1021 の詳細), do NOT use this skill — route to calibre-catalog-read.
• calibre-catalog-read must not be used for those edit intents.

Use this skill when the user asks any of:

• "ID指定でタイトル修正"
• "メタデータ編集"
• title/authors/series/series_index/tags/publisher/pubdate/languages updates

Do NOT use this skill for:

• Read-only lookups (e.g. "ID 1021 を確認して", "ID 1021 の情報を見せて", "show me book 1021")
• Checking what metadata a book currently has without intent to change it
• Those must use calibre-catalog-read

Requirements

• calibredb must be available on PATH in the runtime environment
• subagent-spawn-command-builder installed (for spawn payload generation)
• pdffonts is optional/recommended for PDF evidence checks
• Reachable Calibre Content server URL
  • http://HOST:PORT/#LIBRARY_ID
  • If LIBRARY_ID is unknown, use #- once to list available IDs on the server.
• --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 authentication is enabled, prefer /home/altair/.openclaw/.env:
  • CALIBRE_USERNAME=<user>
  • CALIBRE_PASSWORD=<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.
• Pass --password-env CALIBRE_PASSWORD (username auto-loads from env)
• You can still override explicitly with --username <user>.

Supported fields

Direct fields (set_metadata --field)

• title
• title_sort
• authors (string with & or array)
• author_sort
• series
• series_index
• tags (string or array)
• publisher
• pubdate (YYYY-MM-DD)
• languages
• comments

Helper fields

• comments_html (OC marker block upsert)
• analysis (auto-generates analysis HTML for comments)
• analysis_tags (adds tags)
• tags_merge (default true)
• tags_remove (remove specific tags after merge)

Required execution flow

A. Target confirmation (mandatory)

1. Run read-only lookup to narrow candidates
2. Show id,title,authors,series,series_index
3. Get user confirmation for final target IDs
4. Build JSONL using only confirmed IDs

B. Proposal synthesis (when metadata is missing)

1. Collect evidence from file extraction + web sources
2. Show one merged proposal table with:
   • candidate, source, confidence (high|medium|low)
   • title_sort_candidate, author_sort_candidate
3. Get user decision:
   • approve all
   • approve only: <fields>
   • reject: <fields>
   • edit: <field>=<value>
4. Apply only approved/finalized fields
5. If confidence is low or sources conflict, keep fields empty

C. Apply

1. Run dry-run first (mandatory)
2. Run --apply only after explicit user approval
3. Re-read and report final values

Analysis worker policy

• Use subagent-spawn-command-builder to generate sessions_spawn payload for heavy candidate generation
  • task is required.
  • Profile should include model/thinking/timeout/cleanup for this workflow.
• Use lightweight subagent model for analysis (avoid main heavy model)
• Keep final decisions + dry-run/apply in main

Data flow disclosure

• Local execution:
  • Build calibredb set_metadata commands from JSONL.
  • Read/write local state files (state/runs.json).
• Subagent execution (optional for heavy candidate generation):
  • Uses sessions_spawn via subagent-spawn-command-builder.
  • Text/metadata sent to subagent can reach model endpoints configured by runtime profile.
• Remote write:
  • calibredb set_metadata updates metadata on the target Calibre Content server.

Security rules:

• Prefer env-based password (--password-env CALIBRE_PASSWORD) over inline --password.
• If user does not want external model/subagent processing, keep flow local and skip subagent orchestration.
• In agent/chat execution, do not call calibredb directly for edit operations.
  • Always execute node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs.
• Never run calibre-server from this skill.
  • This workflow always targets an already-running Calibre Content server.

Connection bootstrap (mandatory)

• Do not ask the user for --with-library first.
• First, execute using saved defaults (env) with no explicit --with-library.
  • Scripts auto-load .env and resolve CALIBRE_WITH_LIBRARY / CALIBRE_CONTENT_SERVER_URL.
• Ask user for URL only when command output shows unresolved connection, such as:
  • missing --with-library
  • unable to resolve usable --with-library
  • repeated connection failures for all candidates

Long-run turn-split policy (library-wide)

For library-wide heavy processing, always use turn-split execution.

Unknown-document recovery flow (M3)

Batch sizing rule:

• Keep each unknown-document batch small enough to show full row-by-row results in chat (no representative sampling).
• If unresolved items remain, stop and wait for explicit user instruction to start the next batch.

User intervention checkpoints (fixed)

1. Light pass (metadata-only)

   • Always run this stage by default (no extra user instruction required)
   • Analyze existing metadata only (no file content read)
   • Present a table to user:
     • current file/title
     • recommended title/metadata
     • confidence/evidence summary
   • Stop and wait for user instruction before any deeper stage

2. On user request: page-1 pass

   • Read only the first page and refine proposals
   • Report delta from light pass

3. If still uncertain: deep pass

   • Read first 5 pages + last 5 pages
   • Add web evidence search
   • Produce finalized proposal with confidence + rationale

4. Approval gate

   • Show detailed findings and request explicit approval before apply

Pending and unsupported handling

• Use pending-review tag for unresolved/hold items.
• If document is unresolved in current flow, do not force metadata guesses.
  • Tag with pending-review and keep for follow-up investigation.

Diff report format (for unknown batch runs)

Return full results (not samples):

• execution summary (target/changed/pending/skipped/error)
• full changed list with id + key before/after fields
• full pending list with id + reason
• full error list with id + error summary
• confidence must be expressed as high|medium|low

Runtime artifact policy

• Keep run-state and temporary artifacts only while a run is active.
• On successful completion, remove per-run state/artifacts.
• On failure, keep minimal artifacts only for retry/debug, then clean up after resolution.

Internal orchestration (recommended)

• Use lightweight subagent for all analysis stages
• Keep apply decisions in main session
• Persist run state for each stage in state/runs.json

Turn 1 (start)

1. Main defines scope
2. Main generates spawn payload via subagent-spawn-command-builder (profile example: calibre-meta), then calls sessions_spawn
3. Save run_id/session_key/task via scripts/run_state.mjs upsert
4. Immediately tell the user this is a subagent job and state the execution model used for analysis
5. Reply with "analysis started" and keep normal chat responsive

Turn 2 (completion)

1. Receive subagent completion notice
2. Save result JSON
3. Complete state handling via scripts/handle_completion.mjs --run-id ... --result-json ...
4. Return summarized proposal (apply only when needed)

Run state file:

• state/runs.json

PDF extraction policy

1. Try ebook-convert first
2. If empty/failed, fallback to pdftotext
3. If both fail, switch to web-evidence-first mode

Sort reading policy

• Use user-configured reading_script for Japanese/non-Latin sort fields
  • katakana / hiragana / latin
• Ask once on first use, then reuse for the session
• Default policy is full reading (no truncation)
• Read the "Calibre Content Server" section of TOOLS.md for the configured reading_script value; pass it as a CLI argument when needed.

Usage

Dry-run:

cat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \
  --with-library "http://127.0.0.1:8080/#MyLibrary" \
  --password-env CALIBRE_PASSWORD \
  --lang ja

Dry-run (when default library is preconfigured via env/config):

cat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \
  --password-env CALIBRE_PASSWORD \
  --lang ja

Apply:

cat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \
  --with-library "http://127.0.0.1:8080/#MyLibrary" \
  --password-env CALIBRE_PASSWORD \
  --apply

Do not

• Do not run direct --apply using ambiguous title matches only
• Do not include unconfirmed IDs in apply payload
• Do not auto-fill low-confidence candidates without explicit confirmation
• Do not start a local server with guessed path like ~/Calibre Library