calibre-metadata-apply

SKILL.md

---
name: "calibre-metadata-apply"
description: "Edit Calibre metadata through verified dry-run and apply gates."
metadata: {"openclaw":{"requires":{"bins":["node","calibredb"],"env":["CALIBRE_PASSWORD"]},"optionalBins":["pdffonts"],"optionalEnv":["CALIBRE_USERNAME"],"primaryEnv":"CALIBRE_PASSWORD","localWrites":["skills/calibre-metadata-apply/state/runs.json"],"modifiesRemoteData":["calibre:metadata"]}}
---

# calibre-metadata-apply

Use for Calibre metadata writes. This skill can change remote Calibre metadata.

## Routing

Use when user explicitly asks to edit/fix/update/change:
- title, title_sort
- authors, author_sort
- series, series_index
- tags, publisher, pubdate, languages
- comments, analysis, analysis_tags

Do not use for read-only requests such as `ID1021 を確認して`, 詳細, show/view/check. Route those to `calibre-catalog-read`.

ID + edit verb means this skill. ID without edit verb means read-only.

## Supported Fields

Core fields:
- `title`, `title_sort`
- `authors` as string with `&` or array, `author_sort`
- `series`, `series_index`
- `tags` as string or array, `publisher`, `pubdate` as `YYYY-MM-DD`, `languages`
- `comments`

Extended 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.

## Safety Contract

Required flow:
1. Run read-only lookup to narrow candidates.
2. Show `id,title,authors,series,series_index`.
3. Get user confirmation for target IDs.
4. Build JSONL only for confirmed IDs.
5. Dry-run first.
6. Apply only after explicit user approval.
7. Re-read and report final values.

Never:
- Apply ambiguous title matches.
- Include unconfirmed IDs.
- Auto-fill low-confidence candidates.
- Start `calibre-server`.
- Pass Calibre password inline.
- Use direct `calibredb` for chat/agent edit operations; use wrapper scripts.

## Local Facts

Read the workspace `AGENTS.md` `## Tools` section for Content server URL, library id, auth, and reading script.

Connection bootstrap:
- Do not ask the user for `--with-library` first.
- First use saved defaults with no explicit `--with-library`.
- Scripts auto-load `.env`.
- Non-SSL auth is Digest; do not pass auth-mode/auth-scheme flags.
- Ask for URL only after command output shows unresolved connection.
- Prefer env-based password with `--password-env CALIBRE_PASSWORD`; username auto-loads from env, or override with `--username`.

Requirements: `calibredb` and `node`; `pdffonts` optional/recommended for PDF evidence checks.

## Commands

Dry-run:
    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 --password-env CALIBRE_PASSWORD --lang ja --apply

Run state:
    node skills/calibre-metadata-apply/scripts/run_state.mjs upsert --run-id <RUN_ID> --session-key <RUNTIME_HANDLE> --task <TASK> --state running
    node skills/calibre-metadata-apply/scripts/handle_completion.mjs --run-id <RUN_ID> --result-json /tmp/result.json

## Unknown-Document Recovery

Use when title/author/series are missing or unreliable.

Default stage is light pass:
1. Analyze existing metadata only.
2. Present all rows, not samples.
3. Stop for user instruction before deeper inspection.

On request:
- Page-1 pass: first page only.
- Deep pass: first 5 + last 5 pages and web evidence.
- Apply gate: explicit approval before writes.

Proposal synthesis:
- Collect evidence from file extraction and web sources when metadata is missing.
- Show one merged proposal table with id, current fields, candidate fields, source, confidence high|medium|low, and sort candidates.
- Apply only approved/finalized fields.
- If confidence is low or sources conflict, keep fields empty.
- Use pending-review tag for unresolved/hold items; do not force guesses.

Required report shape for batch recovery:
- execution summary with target/changed/pending/skipped/error.
- full changed list with `id` and key before/after fields.
- full pending list with `id` and reason.
- full error list with `id` and error summary.

## Extraction And Sort

- Try `ebook-convert` first.
- If empty/failed, fallback to `pdftotext`.
- If both fail, switch to web-evidence-first mode.
- Use the Calibre `reading_script` in the workspace `AGENTS.md` `## Tools` section for Japanese/non-Latin sort fields.
- Default policy is full reading, no truncation.
- Ask once on first use only when the workspace `AGENTS.md` `## Tools` section lacks the configured reading script.

## Heavy Analysis

Delegate only independent proposal generation. Main owns target selection, final judgment, dry-run, apply, and reporting.

1. Define a self-contained task with input paths, evidence limits, and output contract.
2. 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.
3. Save the returned run/session identifiers and task with `scripts/run_state.mjs upsert`.
4. Use `sessions_yield` when completion belongs in a later turn. Do not poll session or subagent lists.
5. Save result JSON and run `scripts/handle_completion.mjs --run-id ... --result-json ...`.
6. Return a proposal or apply result only after the existing user gate is satisfied.

Use Swarm only when the user requests a large batch that divides into independent evidence rows. Collector children remain read-only; the main session owns synthesis and every write gate.

Data flow:
- Local execution reads Calibre metadata/files and writes metadata only after approval.
- Child execution may receive extracted source/evidence for candidate generation.
- Child must not apply metadata or message the user.
- If the user declines external model/subagent processing, keep the flow local.