calibre-metadata-apply
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 ID-based title fix (e.g.
ID1011 タイトル修正), this skill is mandatory.
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 route those requests to 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
- config:
~/.config/calibre-metadata-apply/config.json with with_library
- optional library id completion:
CALIBRE_LIBRARY_ID or config library_id
- 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>.
- Optional auth cache:
--save-auth (default file: ~/.config/calibre-metadata-apply/auth.json)
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)
- Run read-only lookup to narrow candidates
- Show
id,title,authors,series,series_index
- Get user confirmation for final target IDs
- Build JSONL using only confirmed IDs
B. Proposal synthesis (when metadata is missing)
- Collect evidence from file extraction + web sources
- Show one merged proposal table with:
candidate, source, confidence (high|medium|low)
title_sort_candidate, author_sort_candidate
- Get user decision:
approve all
approve only: <fields>
reject: <fields>
edit: <field>=<value>
- Apply only approved/finalized fields
- If confidence is low or sources conflict, keep fields empty
C. Apply
- Run dry-run first (mandatory)
- Run
--apply only after explicit user approval
- 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) and optional auth/config files under ~/.config/calibre-metadata-apply/.
- 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:
- Do not use
--save-plain-password unless explicitly instructed by the user.
- 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/config) 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)
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
On user request: page-1 pass
- Read only the first page and refine proposals
- Report delta from light pass
If still uncertain: deep pass
- Read first 5 pages + last 5 pages
- Add web evidence search
- Produce finalized proposal with confidence + rationale
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)
- Main defines scope
- Main generates spawn payload via
subagent-spawn-command-builder (profile example: calibre-meta), then calls sessions_spawn
- Save
run_id/session_key/task via scripts/run_state.mjs upsert
- Immediately tell the user this is a subagent job and state the execution model used for analysis
- Reply with "analysis started" and keep normal chat responsive
Turn 2 (completion)
- Receive subagent completion notice
- Save result JSON
- Complete state handling via
scripts/handle_completion.mjs --run-id ... --result-json ...
- Return summarized proposal (apply only when needed)
Run state file:
PDF extraction policy
- Try
ebook-convert first
- If empty/failed, fallback to
pdftotext
- 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 persist and reuse
- Default policy is full reading (no truncation)
- Config path:
~/.config/calibre-metadata-apply/config.json
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
1---2name: calibre-metadata-apply3description: Primary skill for Calibre metadata edits over a running Content server. Use this for ID-based title/authors/series/series_index/tags/publisher/pubdate/languages updates and controlled apply after confirmation.4metadata:5 source: https://skillmd.com/skills/claw-works/calibre-metadata-apply6 openclaw:7 requires:8 bins:9 - node10 - calibredb11 env:12 - CALIBRE_PASSWORD13 optionalBins:14 - pdffonts15 optionalEnv:16 - CALIBRE_USERNAME17 primaryEnv: CALIBRE_PASSWORD18 dependsOnSkills:19 - subagent-spawn-command-builder20 localWrites:21 - skills/calibre-metadata-apply/state/runs.json22 - ~/.config/calibre-metadata-apply/auth.json23 - ~/.config/calibre-metadata-apply/config.json24 modifiesRemoteData:25 - calibre:metadata26---2728# calibre-metadata-apply2930A skill for updating metadata of existing Calibre books.3132## Skill selection contract (strict)3334- If the user intent is metadata edit/fix/update, this skill is mandatory.35- If the request mentions ID-based title fix (e.g. `ID1011 タイトル修正`), this skill is mandatory.36- `calibre-catalog-read` must not be used for those edit intents.3738Use this skill when the user asks any of:39- "ID指定でタイトル修正"40- "メタデータ編集"41- `title/authors/series/series_index/tags/publisher/pubdate/languages` updates4243Do NOT route those requests to `calibre-catalog-read`.4445## Requirements4647- `calibredb` must be available on PATH in the runtime environment48- `subagent-spawn-command-builder` installed (for spawn payload generation)49- `pdffonts` is optional/recommended for PDF evidence checks50- Reachable Calibre Content server URL51 - `http://HOST:PORT/#LIBRARY_ID`52 - If `LIBRARY_ID` is unknown, use `#-` once to list available IDs on the server.53- `--with-library` can be omitted only when one of these is configured:54 - env: `CALIBRE_WITH_LIBRARY` or `CALIBRE_LIBRARY_URL` or `CALIBRE_CONTENT_SERVER_URL`55 - config: `~/.config/calibre-metadata-apply/config.json` with `with_library`56 - optional library id completion: `CALIBRE_LIBRARY_ID` or config `library_id`57- Host failover (IP change resilience):58 - Optional env: `CALIBRE_SERVER_HOSTS=host1,host2,...`59 - Script auto-tries candidates, including WSL host-side `nameserver` from `/etc/resolv.conf`.60- If authentication is enabled, prefer `/home/altair/.openclaw/.env`:61 - `CALIBRE_USERNAME=<user>`62 - `CALIBRE_PASSWORD=<password>`63- Auth scheme policy for this workflow:64 - Non-SSL deployment assumes **Digest** authentication.65 - Do not pass auth mode arguments such as `--auth-mode` / `--auth-scheme`.66- Pass `--password-env CALIBRE_PASSWORD` (username auto-loads from env)67- You can still override explicitly with `--username <user>`.68- Optional auth cache: `--save-auth` (default file: `~/.config/calibre-metadata-apply/auth.json`)6970## Supported fields7172### Direct fields (`set_metadata --field`)73- `title`74- `title_sort`75- `authors` (string with `&` or array)76- `author_sort`77- `series`78- `series_index`79- `tags` (string or array)80- `publisher`81- `pubdate` (`YYYY-MM-DD`)82- `languages`83- `comments`8485### Helper fields86- `comments_html` (OC marker block upsert)87- `analysis` (auto-generates analysis HTML for comments)88- `analysis_tags` (adds tags)89- `tags_merge` (default `true`)90- `tags_remove` (remove specific tags after merge)9192## Required execution flow9394### A. Target confirmation (mandatory)951. Run read-only lookup to narrow candidates962. Show `id,title,authors,series,series_index`973. Get user confirmation for final target IDs984. Build JSONL using only confirmed IDs99100### B. Proposal synthesis (when metadata is missing)1011. Collect evidence from file extraction + web sources1022. Show one merged proposal table with:103 - `candidate`, `source`, `confidence (high|medium|low)`104 - `title_sort_candidate`, `author_sort_candidate`1053. Get user decision:106 - `approve all`107 - `approve only: <fields>`108 - `reject: <fields>`109 - `edit: <field>=<value>`1104. Apply only approved/finalized fields1115. If confidence is low or sources conflict, keep fields empty112113### C. Apply1141. Run dry-run first (mandatory)1152. Run `--apply` only after explicit user approval1163. Re-read and report final values117118## Analysis worker policy119120- Use `subagent-spawn-command-builder` to generate `sessions_spawn` payload for heavy candidate generation121 - `task` is required.122 - Profile should include model/thinking/timeout/cleanup for this workflow.123- Use lightweight subagent model for analysis (avoid main heavy model)124- Keep final decisions + dry-run/apply in main125126## Data flow disclosure127128- Local execution:129 - Build `calibredb set_metadata` commands from JSONL.130 - Read/write local state files (`state/runs.json`) and optional auth/config files under `~/.config/calibre-metadata-apply/`.131- Subagent execution (optional for heavy candidate generation):132 - Uses `sessions_spawn` via `subagent-spawn-command-builder`.133 - Text/metadata sent to subagent can reach model endpoints configured by runtime profile.134- Remote write:135 - `calibredb set_metadata` updates metadata on the target Calibre Content server.136137Security rules:138- Do not use `--save-plain-password` unless explicitly instructed by the user.139- Prefer env-based password (`--password-env CALIBRE_PASSWORD`) over inline `--password`.140- If user does not want external model/subagent processing, keep flow local and skip subagent orchestration.141- In agent/chat execution, do not call `calibredb` directly for edit operations.142 - Always execute `node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs`.143- Never run `calibre-server` from this skill.144 - This workflow always targets an already-running Calibre Content server.145146## Connection bootstrap (mandatory)147148- Do not ask the user for `--with-library` first.149- First, execute using saved defaults (env/config) with no explicit `--with-library`.150 - Scripts auto-load `.env` and resolve `CALIBRE_WITH_LIBRARY` / `CALIBRE_CONTENT_SERVER_URL`.151- Ask user for URL only when command output shows unresolved connection, such as:152 - `missing --with-library`153 - `unable to resolve usable --with-library`154 - repeated connection failures for all candidates155156## Long-run turn-split policy (library-wide)157158For library-wide heavy processing, always use turn-split execution.159160## Unknown-document recovery flow (M3)161162Batch sizing rule:163- Keep each unknown-document batch small enough to show full row-by-row results in chat (no representative sampling).164- If unresolved items remain, stop and wait for explicit user instruction to start the next batch.165166### User intervention checkpoints (fixed)1671681. **Light pass (metadata-only)**169 - Always run this stage by default (no extra user instruction required)170 - Analyze existing metadata only (no file content read)171 - Present a table to user:172 - current file/title173 - recommended title/metadata174 - confidence/evidence summary175 - Stop and wait for user instruction before any deeper stage1761772. **On user request: page-1 pass**178 - Read only the first page and refine proposals179 - Report delta from light pass1801813. **If still uncertain: deep pass**182 - Read first 5 pages + last 5 pages183 - Add web evidence search184 - Produce finalized proposal with confidence + rationale1851864. **Approval gate**187 - Show detailed findings and request explicit approval before apply188189### Pending and unsupported handling190191- Use `pending-review` tag for unresolved/hold items.192- If document is unresolved in current flow, do not force metadata guesses.193 - Tag with `pending-review` and keep for follow-up investigation.194195### Diff report format (for unknown batch runs)196197Return full results (not samples):198- execution summary (target/changed/pending/skipped/error)199- full changed list with `id` + key before/after fields200- full pending list with `id` + reason201- full error list with `id` + error summary202- confidence must be expressed as `high|medium|low`203204### Runtime artifact policy205206- Keep run-state and temporary artifacts only while a run is active.207- On successful completion, remove per-run state/artifacts.208- On failure, keep minimal artifacts only for retry/debug, then clean up after resolution.209210### Internal orchestration (recommended)211212- Use lightweight subagent for all analysis stages213- Keep apply decisions in main session214- Persist run state for each stage in `state/runs.json`215216### Turn 1 (start)2171. Main defines scope2182. Main generates spawn payload via `subagent-spawn-command-builder` (profile example: `calibre-meta`), then calls `sessions_spawn`2193. Save `run_id/session_key/task` via `scripts/run_state.mjs upsert`2204. Immediately tell the user this is a subagent job and state the execution model used for analysis2215. Reply with "analysis started" and keep normal chat responsive222223### Turn 2 (completion)2241. Receive subagent completion notice2252. Save result JSON2263. Complete state handling via `scripts/handle_completion.mjs --run-id ... --result-json ...`2274. Return summarized proposal (apply only when needed)228229Run state file:230- `state/runs.json`231232## PDF extraction policy2332341. Try `ebook-convert` first2352. If empty/failed, fallback to `pdftotext`2363. If both fail, switch to web-evidence-first mode237238## Sort reading policy239240- Use user-configured `reading_script` for Japanese/non-Latin sort fields241 - `katakana` / `hiragana` / `latin`242- Ask once on first use, then persist and reuse243- Default policy is full reading (no truncation)244- Config path: `~/.config/calibre-metadata-apply/config.json`245 - key: `reading_script`246247## Usage248249Dry-run:250251```bash252cat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \253 --with-library "http://127.0.0.1:8080/#MyLibrary" \254 --password-env CALIBRE_PASSWORD \255 --lang ja256```257258Dry-run (when default library is preconfigured via env/config):259260```bash261cat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \262 --password-env CALIBRE_PASSWORD \263 --lang ja264```265266Apply:267268```bash269cat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \270 --with-library "http://127.0.0.1:8080/#MyLibrary" \271 --password-env CALIBRE_PASSWORD \272 --apply273```274275## Do not276277- Do not run direct `--apply` using ambiguous title matches only278- Do not include unconfirmed IDs in apply payload279- Do not auto-fill low-confidence candidates without explicit confirmation280- Do not start a local server with guessed path like `~/Calibre Library`