calibre-metadata-apply_skill

Overview

This skill applies metadata updates to existing Calibre books by generating and running calibredb set_metadata commands against a Calibre Content server. It is designed for controlled, auditable edits after targets are confirmed by a read-only lookup and supports dry-run verification before any write. The workflow emphasizes evidence-driven proposals, user approval gates, and secure credential handling.

How this skill works

The skill inspects confirmed Calibre book IDs and builds JSONL change payloads that map fields to update. It can synthesize proposals from file-extracted evidence and web sources using an optional lightweight subagent, presents a merged proposal with confidence levels, then runs a mandatory dry-run and, after explicit approval, performs calibredb set_metadata calls to apply changes. Credential use prefers environment variables and avoids storing plain passwords.

When to use it

• When you need to make controlled metadata edits after confirming exact Calibre IDs.
• When metadata is incomplete and you want evidence-based proposals before applying changes.
• When you require a dry-run verification step prior to modifying a Calibre library.
• When working with libraries behind a Calibre Content server that requires authentication.
• When processing small batches that must be shown row-by-row for user review.

Best practices

• Always run the mandatory read-only lookup and confirm target IDs before building changes.
• Use the dry-run mode first and review the re-read results before --apply.
• Prefer environment-based credentials (CALIBRE_PASSWORD + auto-loaded username) over inline passwords.
• Use the subagent only for heavy candidate generation; keep final approvals and applies in the main session.
• Tag unresolved or conflicting items with pending-review and stop for explicit user instruction.

Example use cases

• Fixing author_sort and title_sort fields across a handful of confirmed IDs after manual review.
• Merging tags and removing deprecated tags with tags_merge and tags_remove options in a controlled run.
• Running a light-pass metadata-only scan to propose changes, then letting a user approve or edit proposals.
• Performing a page-1 or deep pass for uncertain PDFs to generate higher-confidence proposals before applying.
• Batch-applying publisher, pubdate, or language fields for books where evidence extraction produced a high-confidence match.