{"id":"12421c3d-1c34-4ecb-95e1-d61ea0edf4fa","entityType":"agent","slug":"clawhub-nextaltair-calibre-metadata-apply","name":"calibre-metadata-apply","canonicalUrl":"https://www.xpersona.co/agent/clawhub-nextaltair-calibre-metadata-apply","canonicalPath":"/agent/clawhub-nextaltair-calibre-metadata-apply","generatedAt":"2026-10-09T21:36:56.796Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T16:29:20.216Z","emptyReason":null},"description":"Edit Calibre metadata through verified dry-run and apply gates.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.3K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s1769m2r7tj3d8eqerva8kpwkx83nn9e:calibre-metadata-apply","sourceUrl":"https://clawhub.ai/nextaltair/calibre-metadata-apply","homepage":"https://clawhub.ai/nextaltair/skills/calibre-metadata-apply","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/nextaltair/calibre-metadata-apply","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/nextaltair/skills/calibre-metadata-apply","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":58,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"calibre-metadata-apply technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T16:29:20.216Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T16:29:20.216Z","emptyReason":null},"stars":null,"forks":null,"downloads":2310,"packageName":null,"latestVersion":"1.0.6","tractionLabel":"2.3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T16:29:20.215Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T16:29:20.216Z","lastCrawledAt":"2026-10-09T16:29:20.215Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T16:29:20.215Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.6","createdAt":"2026-07-30T03:04:09.007Z","changelog":"Update local configuration references from retired TOOLS.md to the AGENTS.md Tools section.","fileCount":7,"zipByteSize":15804},{"version":"1.0.5","createdAt":"2026-07-28T07:48:01.710Z","changelog":"OpenClaw sessions_spawn direct delegation; remove shared payload-builder dependency.","fileCount":7,"zipByteSize":15712},{"version":"1.0.4","createdAt":"2026-04-04T10:51:12.595Z","changelog":"calibre-metadata-apply 1.0.4 - Clarified that this skill must only be used for metadata edit/fix/update operations, never for read-only lookups even if IDs are mentioned. - Expanded and reworded the skill selection contract for precise routing: now explicitly states not to use this skill for view/confirm/check requests and to always use calibre-catalog-read for those cases. - Updated examples and guidance for when to use (and not use) the skill. - Enhanced distinction between write operations and read-only operations in documentation.","fileCount":7,"zipByteSize":17557},{"version":"1.0.3","createdAt":"2026-04-04T04:23:02.229Z","changelog":"refactor: migrate user config from per-skill config files to TOOLS.md (#3)","fileCount":6,"zipByteSize":16094},{"version":"1.0.2","createdAt":"2026-03-21T00:33:39.300Z","changelog":"**Summary:** This version introduces a stricter routing/selection policy and expands environment and connection handling for safer and more resilient metadata edits. - Enforces that this skill must be used for all Calibre metadata edit/update requests, especially for ID-based requests; edit intent must not be routed to catalogue read-only skills. - Documents new environment/config auto-resolution for `--with-library` including support for default URLs, library ID completion, and failover to alternate hosts. - Clarifies connection bootstrap flow: do not prompt the user for connection details until all autodetection fails. - Adds security rules: never run direct `calibredb` edit in agent/chat; always route edits via the skill's script. - Improves documentation for field mapping, authentication scheme, helper fields, and host failover mechanisms. - Tightens execution contract, preventing accidental or ambiguous edits.","fileCount":6,"zipByteSize":16812},{"version":"1.0.1","createdAt":"2026-02-13T14:38:44.746Z","changelog":"calibre-metadata-apply 1.0.1 - Added detailed metadata about required/optional binaries, environment variables, and local/remote side effects to SKILL.md. - Documented security rules for authentication and handling of plain passwords. - Clarified data flow: local state, subagent orchestration, and remote write behavior. - Noted optional use of `pdffonts` for PDF evidence in requirements. - No functional changes to code logic—documentation and metadata enhancements only.","fileCount":6,"zipByteSize":12885},{"version":"1.0.0","createdAt":"2026-02-13T13:23:17.625Z","changelog":"- Migrated scripts from Python to Node.js (.py → .mjs) for all core logic and state handling. - Updated authentication flow: prefer loading Calibre credentials from environment variables (`CALIBRE_USERNAME`, `CALIBRE_PASSWORD`) and use `--password-env` option. - Revised usage examples to use Node.js command lines for metadata operations. - Internal orchestration now calls mjs scripts (not Python) for run state and job completion. - Documentation updated throughout to reflect these code and flow changes.","fileCount":6,"zipByteSize":12204},{"version":"0.1.0","createdAt":"2026-02-12T14:07:08.557Z","changelog":"Initial release of calibre-metadata-apply. - Apply metadata updates to existing Calibre books via calibredb and Content server. - Supports controlled, audited metadata edits: fields include title, authors, series, tags, publisher, pubdate, languages, and comments. - Implements multi-stage proposal/approval workflow with confidence grading for safe, batch metadata changes. - Requires target confirmation through user-reviewed ID selection before updates are applied. - Includes dry-run by default; explicit user approval required for live changes. - Robust batch, error, artifact, and approval/reporting policies for safe, reviewable metadata updates.","fileCount":6,"zipByteSize":12150}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1769m2r7tj3d8eqerva8kpwkx83nn9e:calibre-metadata-apply","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s1769m2r7tj3d8eqerva8kpwkx83nn9e:calibre-metadata-apply` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/nextaltair/calibre-metadata-apply before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-nextaltair-calibre-metadata-apply/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-nextaltair-calibre-metadata-apply/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-nextaltair-calibre-metadata-apply/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-nextaltair-calibre-metadata-apply/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-nextaltair-calibre-metadata-apply/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-nextaltair-calibre-metadata-apply/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T21:36:56.793Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-nextaltair-calibre-metadata-apply/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-nextaltair-calibre-metadata-apply/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-nextaltair-calibre-metadata-apply/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-nextaltair-calibre-metadata-apply/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T16:29:20.216Z","emptyReason":null},"readme":"Skill: calibre-metadata-apply\n\nOwner: nextaltair\n\nSummary: Edit Calibre metadata through verified dry-run and apply gates.\n\nTags: latest:1.0.6\n\nVersion history:\n\nv1.0.6 | 2026-07-30T03:04:09.007Z | user\n\nUpdate local configuration references from retired TOOLS.md to the AGENTS.md Tools section.\n\nv1.0.5 | 2026-07-28T07:48:01.710Z | user\n\nOpenClaw sessions_spawn direct delegation; remove shared payload-builder dependency.\n\nv1.0.4 | 2026-04-04T10:51:12.595Z | auto\n\ncalibre-metadata-apply 1.0.4\n\n- Clarified that this skill must only be used for metadata edit/fix/update operations, never for read-only lookups even if IDs are mentioned.\n- Expanded and reworded the skill selection contract for precise routing: now explicitly states not to use this skill for view/confirm/check requests and to always use calibre-catalog-read for those cases.\n- Updated examples and guidance for when to use (and not use) the skill.\n- Enhanced distinction between write operations and read-only operations in documentation.\n\nv1.0.3 | 2026-04-04T04:23:02.229Z | user\n\nrefactor: migrate user config from per-skill config files to TOOLS.md (#3)\n\nv1.0.2 | 2026-03-21T00:33:39.300Z | auto\n\n**Summary:** This version introduces a stricter routing/selection policy and expands environment and connection handling for safer and more resilient metadata edits.\n\n- Enforces that this skill must be used for all Calibre metadata edit/update requests, especially for ID-based requests; edit intent must not be routed to catalogue read-only skills.\n- Documents new environment/config auto-resolution for `--with-library` including support for default URLs, library ID completion, and failover to alternate hosts.\n- Clarifies connection bootstrap flow: do not prompt the user for connection details until all autodetection fails.\n- Adds security rules: never run direct `calibredb` edit in agent/chat; always route edits via the skill's script.\n- Improves documentation for field mapping, authentication scheme, helper fields, and host failover mechanisms.\n- Tightens execution contract, preventing accidental or ambiguous edits.\n\nv1.0.1 | 2026-02-13T14:38:44.746Z | auto\n\ncalibre-metadata-apply 1.0.1\n\n- Added detailed metadata about required/optional binaries, environment variables, and local/remote side effects to SKILL.md.\n- Documented security rules for authentication and handling of plain passwords.\n- Clarified data flow: local state, subagent orchestration, and remote write behavior.\n- Noted optional use of `pdffonts` for PDF evidence in requirements.\n- No functional changes to code logic—documentation and metadata enhancements only.\n\nv1.0.0 | 2026-02-13T13:23:17.625Z | auto\n\n- Migrated scripts from Python to Node.js (.py → .mjs) for all core logic and state handling.\n- Updated authentication flow: prefer loading Calibre credentials from environment variables (`CALIBRE_USERNAME`, `CALIBRE_PASSWORD`) and use `--password-env` option.\n- Revised usage examples to use Node.js command lines for metadata operations.\n- Internal orchestration now calls mjs scripts (not Python) for run state and job completion.\n- Documentation updated throughout to reflect these code and flow changes.\n\nv0.1.0 | 2026-02-12T14:07:08.557Z | auto\n\nInitial release of calibre-metadata-apply.\n\n- Apply metadata updates to existing Calibre books via calibredb and Content server.\n- Supports controlled, audited metadata edits: fields include title, authors, series, tags, publisher, pubdate, languages, and comments.\n- Implements multi-stage proposal/approval workflow with confidence grading for safe, batch metadata changes.\n- Requires target confirmation through user-reviewed ID selection before updates are applied.\n- Includes dry-run by default; explicit user approval required for live changes.\n- Robust batch, error, artifact, and approval/reporting policies for safe, reviewable metadata updates.\n\nArchive index:\n\nArchive v1.0.6: 7 files, 15804 bytes\n\nFiles: README.md (6047b), scripts/calibredb_apply.mjs (18153b), scripts/handle_completion.mjs (1989b), scripts/run_state.mjs (3259b), skill-card.md (2171b), SKILL.md (6033b), _meta.json (141b)\n\nFile v1.0.6:SKILL.md\n\n---\nname: \"calibre-metadata-apply\"\ndescription: \"Edit Calibre metadata through verified dry-run and apply gates.\"\nmetadata: {\"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\"]}}\n---\n\n# calibre-metadata-apply\n\nUse for Calibre metadata writes. This skill can change remote Calibre metadata.\n\n## Routing\n\nUse when user explicitly asks to edit/fix/update/change:\n- title, title_sort\n- authors, author_sort\n- series, series_index\n- tags, publisher, pubdate, languages\n- comments, analysis, analysis_tags\n\nDo not use for read-only requests such as `ID1021 を確認して`, 詳細, show/view/check. Route those to `calibre-catalog-read`.\n\nID + edit verb means this skill. ID without edit verb means read-only.\n\n## Supported Fields\n\nCore fields:\n- `title`, `title_sort`\n- `authors` as string with `&` or array, `author_sort`\n- `series`, `series_index`\n- `tags` as string or array, `publisher`, `pubdate` as `YYYY-MM-DD`, `languages`\n- `comments`\n\nExtended fields:\n- `comments_html`: OC marker block upsert.\n- `analysis`: auto-generates analysis HTML for comments.\n- `analysis_tags`: adds tags.\n- `tags_merge`: default true.\n- `tags_remove`: remove specific tags after merge.\n\n## Safety Contract\n\nRequired flow:\n1. Run read-only lookup to narrow candidates.\n2. Show `id,title,authors,series,series_index`.\n3. Get user confirmation for target IDs.\n4. Build JSONL only for confirmed IDs.\n5. Dry-run first.\n6. Apply only after explicit user approval.\n7. Re-read and report final values.\n\nNever:\n- Apply ambiguous title matches.\n- Include unconfirmed IDs.\n- Auto-fill low-confidence candidates.\n- Start `calibre-server`.\n- Pass Calibre password inline.\n- Use direct `calibredb` for chat/agent edit operations; use wrapper scripts.\n\n## Local Facts\n\nRead the workspace `AGENTS.md` `## Tools` section for Content server URL, library id, auth, and reading script.\n\nConnection bootstrap:\n- Do not ask the user for `--with-library` first.\n- First use saved defaults with no explicit `--with-library`.\n- Scripts auto-load `.env`.\n- Non-SSL auth is Digest; do not pass auth-mode/auth-scheme flags.\n- Ask for URL only after command output shows unresolved connection.\n- Prefer env-based password with `--password-env CALIBRE_PASSWORD`; username auto-loads from env, or override with `--username`.\n\nRequirements: `calibredb` and `node`; `pdffonts` optional/recommended for PDF evidence checks.\n\n## Commands\n\nDry-run:\n cat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs --password-env CALIBRE_PASSWORD --lang ja\n\nApply:\n cat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs --password-env CALIBRE_PASSWORD --lang ja --apply\n\nRun state:\n node skills/calibre-metadata-apply/scripts/run_state.mjs upsert --run-id --session-key --task --state running\n node skills/calibre-metadata-apply/scripts/handle_completion.mjs --run-id --result-json /tmp/result.json\n\n## Unknown-Document Recovery\n\nUse when title/author/series are missing or unreliable.\n\nDefault stage is light pass:\n1. Analyze existing metadata only.\n2. Present all rows, not samples.\n3. Stop for user instruction before deeper inspection.\n\nOn request:\n- Page-1 pass: first page only.\n- Deep pass: first 5 + last 5 pages and web evidence.\n- Apply gate: explicit approval before writes.\n\nProposal synthesis:\n- Collect evidence from file extraction and web sources when metadata is missing.\n- Show one merged proposal table with id, current fields, candidate fields, source, confidence high|medium|low, and sort candidates.\n- Apply only approved/finalized fields.\n- If confidence is low or sources conflict, keep fields empty.\n- Use pending-review tag for unresolved/hold items; do not force guesses.\n\nRequired report shape for batch recovery:\n- execution summary with target/changed/pending/skipped/error.\n- full changed list with `id` and key before/after fields.\n- full pending list with `id` and reason.\n- full error list with `id` and error summary.\n\n## Extraction And Sort\n\n- Try `ebook-convert` first.\n- If empty/failed, fallback to `pdftotext`.\n- If both fail, switch to web-evidence-first mode.\n- Use the Calibre `reading_script` in the workspace `AGENTS.md` `## Tools` section for Japanese/non-Latin sort fields.\n- Default policy is full reading, no truncation.\n- Ask once on first use only when the workspace `AGENTS.md` `## Tools` section lacks the configured reading script.\n\n## Heavy Analysis\n\nDelegate only independent proposal generation. Main owns target selection, final judgment, dry-run, apply, and reporting.\n\n1. Define a self-contained task with input paths, evidence limits, and output contract.\n2. Call OpenClaw `sessions_spawn` with the live tool schema:\n - `runtime: \"subagent\"`\n - `agentId: \"calibre-reader\"`\n - `mode: \"run\"`\n - `context: \"isolated\"`\n - `lightContext: true`\n - omit `model` and `thinking`; the target agent profile owns them.\n3. Save the returned run/session identifiers and task with `scripts/run_state.mjs upsert`.\n4. Use `sessions_yield` when completion belongs in a later turn. Do not poll session or subagent lists.\n5. Save result JSON and run `scripts/handle_completion.mjs --run-id ... --result-json ...`.\n6. Return a proposal or apply result only after the existing user gate is satisfied.\n\nUse 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.\n\nData flow:\n- Local execution reads Calibre metadata/files and writes metadata only after approval.\n- Child execution may receive extracted source/evidence for candidate generation.\n- Child must not apply metadata or message the user.\n- If the user declines external model/subagent processing, keep the flow local.\n\nFile v1.0.6:README.md\n\n# calibre-metadata-apply\n\n`calibredb` を使って、既存Calibre書籍のメタデータを更新するスキルです。\n\n## このスキルの目的\n\nこのスキルは、Calibreライブラリのメタデータ運用を\n**「安全に・継続的に・監査可能に」回す** ための実務スキルです。\n\n### 1) 何を解決するか\n\n- 手作業で崩れやすいメタデータ整備（title/authors/publisher/pubdate/tags/sort）を定型化\n- 1冊編集とライブラリ横断編集を同じ運用ルールで実施\n- 長時間ジョブでもチャットを止めずに進行（ターン分割）\n\n### 2) 何を自動化するか\n\n- 1冊単位の確定編集（確認→dry-run→apply→検証）\n- ライブラリ横断の推定タグ付与（本文ではなく既存メタデータのみを利用）\n- 高確信候補の自動適用と、低確信候補の保留\n\n### 3) 何をしないか（境界）\n\n- 曖昧な対象に対する即時apply\n- 根拠が弱い候補の無条件上書き\n- 本文解析が必要な重処理をmainターンで同期実行\n\n### 4) 想定ユースケース\n\n- 「ID指定で論文書誌を修正したい」\n- 「マニュアルらしい本に `マニュアル/Manual` を一括付与したい」\n- 「論文らしい本を横断抽出して `論文` タグを付けたい」\n\n### 5) 運用ポリシー（要点）\n\n- 高確信な提案のみ自動適用\n- 低確信・衝突ケースは保留/再処理\n- 保留は `pending-review` タグを付与して管理\n- confidence表現は `high/medium/low` に統一\n- 長時間処理はターン分割（開始ACK→完了報告）\n- 実行中の状態/一時ファイルは完了時に削除（失敗時のみ最小限保持）\n\n## セットアップ\n\n1. このスキルを実行する環境にCalibreをインストールする\n - 必須: `calibredb`\n2. PDF調査用に `pdffonts` を使えるようにする（例: `poppler-utils`）\n3. `calibredb` と `pdffonts` が `PATH` で実行できることを確認する\n4. Calibre Content server に到達できることを確認する\n5. `--with-library` は次の形式で指定する\n - `http://HOST:PORT/#LIBRARY_ID`\n - localhost前提にしない（明示的なHOST:PORTを使う）\n - 省略する場合は以下のどれかを事前設定する\n - env: `CALIBRE_WITH_LIBRARY` / `CALIBRE_LIBRARY_URL` / `CALIBRE_CONTENT_SERVER_URL`\n - config: `~/.config/calibre-metadata-apply/config.json` の `with_library`\n - URLに`#LIBRARY_ID`が無い場合は `CALIBRE_LIBRARY_ID` か config `library_id` で補完可能\n - IP変更対策:\n - `CALIBRE_SERVER_HOSTS=host1,host2,...` を設定すると候補を順に試行\n - WSLでは `/etc/resolv.conf` の `nameserver` も自動候補に追加\n - `LIBRARY_ID` が不明な場合は `#-` で一覧確認できる\n - 例: `calibredb list --with-library \"http://HOST:PORT/#-\" --username ... --password ...`\n6. 認証が有効な場合は次を指定する\n - `--username `\n - `--password-env ` または `--password `\n - 認証方式は非SSL運用前提でDigest固定(自動)とし、`--auth-mode` / `--auth-scheme` は使わない\n7. 認証情報を保存して再利用したい場合は `--save-auth` を使う\n - 既定保存先: `~/.config/calibre-metadata-apply/auth.json`\n - 既定では `username` と `password_env` を保存\n - 平文パスワードも保存する場合のみ `--save-plain-password` を追加\n\n### ユーザーが先に実行すること（例: Ubuntu/WSL）\n\n```bash\nsudo apt update\nsudo apt install -y calibre poppler-utils\n```\n\n## 重要\n\nOpenClawが入っているだけでは不十分です。実行環境側に `calibredb` が必要です。\nチャット実行時は `calibredb` 直接実行ではなく、必ず `node scripts/calibredb_apply.mjs` を使ってください。\nこの運用では既存のCalibre Content serverに接続するため、`calibre-server` を起動する手順は不要です。\n\nWindowsではDefender Controlled Folder Access等の影響で書き込みが失敗する場合があります。\n`WinError 2/5` などのパス/アクセス系エラーが出る場合は、Calibreライブラリフォルダや実行バイナリを許可リストに追加してください。\n\n## 安全モデル\n\n- 入力はJSONL（1行=1更新）\n- `id` 必須\n- デフォルトはdry-run（`--apply` 指定時のみ書き込み）\n\n## ライブラリ横断処理（ターン分割）\n\n長時間処理はターン分割で実行し、チャット継続性を優先します。\n\n- 開始ターン:\n - scopeと出力契約を含む自己完結したtaskを作る\n - OpenClaw `sessions_spawn`を直接呼んで解析を委譲\n - `scripts/run_state.mjs` で実行状態を記録\n- 完了ターン: 完了通知後、`scripts/handle_completion.mjs` で状態を片付けて結果を提示\n- state保存先: `state/runs.json`\n\n### Subagent runtime\n\nmodel・thinkingのローカル既定値は設定済みの`calibre-reader` agent profileで管理します。\n\n- OpenClaw `sessions_spawn`を直接呼ぶ。\n- toolが公開する現在のschemaに従い、別の共通payloadを生成しない。\n- mainだけが候補の採否、dry-run、apply、ユーザー応答を担当する。\n\n## 認証キャッシュ（初回保存）\n\n初回だけ認証情報を保存しておくと、以後は `--username` / `--password-env` を省略できます。\n\n```bash\ncat references/changes.example.jsonl | node scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --save-auth\n```\n\n平文パスワードも保存したい場合（非推奨）は次を追加:\n\n```bash\n--save-plain-password\n```\n\n## クイックテスト（dry-run）\n\n```bash\ncat references/changes.example.jsonl | node scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\"\n```\n\n`--with-library` を省略したい場合は、先に `CALIBRE_WITH_LIBRARY` などを設定してください。\n\nFile v1.0.6:_meta.json\n\n{\n \"ownerId\": \"kn747bx1r2jrbbyca61v6k06397zy93t\",\n \"slug\": \"calibre-metadata-apply\",\n \"version\": \"1.0.6\",\n \"publishedAt\": 1785380649007\n}\n\nFile v1.0.6:skill-card.md\n\n## Description:\n\nEdit Calibre metadata through verified dry-run and apply gates.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[nextaltair](https://clawhub.ai/user/nextaltair)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and operators use this skill to safely update existing Calibre book metadata, from single-book fixes to library-wide tag operations, using confirmation, dry-run, apply, and verification gates.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can modify remote Calibre metadata and incorrect targets or values could overwrite useful library records.\n\nMitigation: Use the documented candidate narrowing, ID confirmation, dry-run, explicit approval, and re-read steps before and after any apply operation.\n\nRisk: Credential handling and automatic Calibre host probing require trust in the workspace and endpoint configuration.\n\nMitigation: Install only in trusted workspaces, prefer explicit Calibre endpoint settings, pass passwords through environment variables, and use a limited Calibre account where possible.\n\nRisk: Untrusted analysis JSON or raw comments_html could persist unsafe or misleading HTML in Calibre comments.\n\nMitigation: Do not feed untrusted analysis JSON or raw comments_html into apply mode; review generated comments in dry-run output before approving writes.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/nextaltair/skills/calibre-metadata-apply)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Markdown, Shell commands, Configuration, JSON]\n\n**Output Format:** [Markdown guidance with shell commands and JSONL/JSON apply reports]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Uses dry-run output before apply mode and reports final metadata changes after verification.]\n\n## Skill Version(s):\n\n1.0.6 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.0.5: 7 files, 15712 bytes\n\nFiles: README.md (6023b), scripts/calibredb_apply.mjs (18121b), scripts/handle_completion.mjs (1989b), scripts/run_state.mjs (3259b), skill-card.md (2276b), SKILL.md (5885b), _meta.json (141b)\n\nFile v1.0.5:SKILL.md\n\n---\nname: \"calibre-metadata-apply\"\ndescription: \"Edit Calibre title, authors, series, tags, dates, comments, and analysis metadata with dry-run/apply gates.\"\nmetadata: {\"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\"]}}\n---\n\n# calibre-metadata-apply\n\nUse for Calibre metadata writes. This skill can change remote Calibre metadata.\n\n## Routing\n\nUse when user explicitly asks to edit/fix/update/change:\n- title, title_sort\n- authors, author_sort\n- series, series_index\n- tags, publisher, pubdate, languages\n- comments, analysis, analysis_tags\n\nDo not use for read-only requests such as `ID1021 を確認して`, 詳細, show/view/check. Route those to `calibre-catalog-read`.\n\nID + edit verb means this skill. ID without edit verb means read-only.\n\n## Supported Fields\n\nCore fields:\n- `title`, `title_sort`\n- `authors` as string with `&` or array, `author_sort`\n- `series`, `series_index`\n- `tags` as string or array, `publisher`, `pubdate` as `YYYY-MM-DD`, `languages`\n- `comments`\n\nExtended fields:\n- `comments_html`: OC marker block upsert.\n- `analysis`: auto-generates analysis HTML for comments.\n- `analysis_tags`: adds tags.\n- `tags_merge`: default true.\n- `tags_remove`: remove specific tags after merge.\n\n## Safety Contract\n\nRequired flow:\n1. Run read-only lookup to narrow candidates.\n2. Show `id,title,authors,series,series_index`.\n3. Get user confirmation for target IDs.\n4. Build JSONL only for confirmed IDs.\n5. Dry-run first.\n6. Apply only after explicit user approval.\n7. Re-read and report final values.\n\nNever:\n- Apply ambiguous title matches.\n- Include unconfirmed IDs.\n- Auto-fill low-confidence candidates.\n- Start `calibre-server`.\n- Pass Calibre password inline.\n- Use direct `calibredb` for chat/agent edit operations; use wrapper scripts.\n\n## Local Facts\n\nRead TOOLS.md for Content server URL, library id, auth, reading script, and optional subagent model defaults.\n\nConnection bootstrap:\n- Do not ask the user for `--with-library` first.\n- First use saved defaults with no explicit `--with-library`.\n- Scripts auto-load `.env`.\n- Non-SSL auth is Digest; do not pass auth-mode/auth-scheme flags.\n- Ask for URL only after command output shows unresolved connection.\n- Prefer env-based password with `--password-env CALIBRE_PASSWORD`; username auto-loads from env, or override with `--username`.\n\nRequirements: `calibredb` and `node`; `pdffonts` optional/recommended for PDF evidence checks.\n\n## Commands\n\nDry-run:\n cat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs --password-env CALIBRE_PASSWORD --lang ja\n\nApply:\n cat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs --password-env CALIBRE_PASSWORD --lang ja --apply\n\nRun state:\n node skills/calibre-metadata-apply/scripts/run_state.mjs upsert --run-id --session-key --task --state running\n node skills/calibre-metadata-apply/scripts/handle_completion.mjs --run-id --result-json /tmp/result.json\n\n## Unknown-Document Recovery\n\nUse when title/author/series are missing or unreliable.\n\nDefault stage is light pass:\n1. Analyze existing metadata only.\n2. Present all rows, not samples.\n3. Stop for user instruction before deeper inspection.\n\nOn request:\n- Page-1 pass: first page only.\n- Deep pass: first 5 + last 5 pages and web evidence.\n- Apply gate: explicit approval before writes.\n\nProposal synthesis:\n- Collect evidence from file extraction and web sources when metadata is missing.\n- Show one merged proposal table with id, current fields, candidate fields, source, confidence high|medium|low, and sort candidates.\n- Apply only approved/finalized fields.\n- If confidence is low or sources conflict, keep fields empty.\n- Use pending-review tag for unresolved/hold items; do not force guesses.\n\nRequired report shape for batch recovery:\n- execution summary with target/changed/pending/skipped/error.\n- full changed list with `id` and key before/after fields.\n- full pending list with `id` and reason.\n- full error list with `id` and error summary.\n\n## Extraction And Sort\n\n- Try `ebook-convert` first.\n- If empty/failed, fallback to `pdftotext`.\n- If both fail, switch to web-evidence-first mode.\n- Use TOOLS.md Calibre `reading_script` for Japanese/non-Latin sort fields.\n- Default policy is full reading, no truncation.\n- Ask once on first use only when TOOLS.md lacks the configured reading script.\n\n## Heavy Analysis\n\nUse native subagent delegation only for heavy proposal generation. Main owns final decisions, dry-run, apply, and final report.\n\n1. Main defines scope and a self-contained task with required input paths, evidence limits, and output contract.\n2. Call OpenClaw `sessions_spawn` directly with the self-contained task.\n - Follow the schema exposed by the current tool.\n - Do not generate or reuse a separate shared spawn payload.\n3. Use model/thinking defaults from TOOLS.md only when an override is needed.\n4. Save `run_id`, the returned OpenClaw session handle, and task via `scripts/run_state.mjs upsert`.\n5. Keep normal chat responsive and consume the OpenClaw completion event; do not busy-poll.\n6. Save result JSON and run `scripts/handle_completion.mjs --run-id ... --result-json ...`.\n7. Return a proposal or apply result only after the existing user gate is satisfied.\n\nData flow:\n- Local execution reads Calibre metadata/files and writes Calibre metadata only after approval.\n- Optional subagent execution may receive extracted source/evidence for heavy candidate generation.\n- Subagent must not apply metadata or message the user.\n- If user does not want external model/subagent processing, keep flow local and skip delegation.\n\nFile v1.0.5:README.md\n\n# calibre-metadata-apply\n\n`calibredb` を使って、既存Calibre書籍のメタデータを更新するスキルです。\n\n## このスキルの目的\n\nこのスキルは、Calibreライブラリのメタデータ運用を\n**「安全に・継続的に・監査可能に」回す** ための実務スキルです。\n\n### 1) 何を解決するか\n\n- 手作業で崩れやすいメタデータ整備（title/authors/publisher/pubdate/tags/sort）を定型化\n- 1冊編集とライブラリ横断編集を同じ運用ルールで実施\n- 長時間ジョブでもチャットを止めずに進行（ターン分割）\n\n### 2) 何を自動化するか\n\n- 1冊単位の確定編集（確認→dry-run→apply→検証）\n- ライブラリ横断の推定タグ付与（本文ではなく既存メタデータのみを利用）\n- 高確信候補の自動適用と、低確信候補の保留\n\n### 3) 何をしないか（境界）\n\n- 曖昧な対象に対する即時apply\n- 根拠が弱い候補の無条件上書き\n- 本文解析が必要な重処理をmainターンで同期実行\n\n### 4) 想定ユースケース\n\n- 「ID指定で論文書誌を修正したい」\n- 「マニュアルらしい本に `マニュアル/Manual` を一括付与したい」\n- 「論文らしい本を横断抽出して `論文` タグを付けたい」\n\n### 5) 運用ポリシー（要点）\n\n- 高確信な提案のみ自動適用\n- 低確信・衝突ケースは保留/再処理\n- 保留は `pending-review` タグを付与して管理\n- confidence表現は `high/medium/low` に統一\n- 長時間処理はターン分割（開始ACK→完了報告）\n- 実行中の状態/一時ファイルは完了時に削除（失敗時のみ最小限保持）\n\n## セットアップ\n\n1. このスキルを実行する環境にCalibreをインストールする\n - 必須: `calibredb`\n2. PDF調査用に `pdffonts` を使えるようにする（例: `poppler-utils`）\n3. `calibredb` と `pdffonts` が `PATH` で実行できることを確認する\n4. Calibre Content server に到達できることを確認する\n5. `--with-library` は次の形式で指定する\n - `http://HOST:PORT/#LIBRARY_ID`\n - localhost前提にしない（明示的なHOST:PORTを使う）\n - 省略する場合は以下のどれかを事前設定する\n - env: `CALIBRE_WITH_LIBRARY` / `CALIBRE_LIBRARY_URL` / `CALIBRE_CONTENT_SERVER_URL`\n - config: `~/.config/calibre-metadata-apply/config.json` の `with_library`\n - URLに`#LIBRARY_ID`が無い場合は `CALIBRE_LIBRARY_ID` か config `library_id` で補完可能\n - IP変更対策:\n - `CALIBRE_SERVER_HOSTS=host1,host2,...` を設定すると候補を順に試行\n - WSLでは `/etc/resolv.conf` の `nameserver` も自動候補に追加\n - `LIBRARY_ID` が不明な場合は `#-` で一覧確認できる\n - 例: `calibredb list --with-library \"http://HOST:PORT/#-\" --username ... --password ...`\n6. 認証が有効な場合は次を指定する\n - `--username `\n - `--password-env ` または `--password `\n - 認証方式は非SSL運用前提でDigest固定(自動)とし、`--auth-mode` / `--auth-scheme` は使わない\n7. 認証情報を保存して再利用したい場合は `--save-auth` を使う\n - 既定保存先: `~/.config/calibre-metadata-apply/auth.json`\n - 既定では `username` と `password_env` を保存\n - 平文パスワードも保存する場合のみ `--save-plain-password` を追加\n\n### ユーザーが先に実行すること（例: Ubuntu/WSL）\n\n```bash\nsudo apt update\nsudo apt install -y calibre poppler-utils\n```\n\n## 重要\n\nOpenClawが入っているだけでは不十分です。実行環境側に `calibredb` が必要です。\nチャット実行時は `calibredb` 直接実行ではなく、必ず `node scripts/calibredb_apply.mjs` を使ってください。\nこの運用では既存のCalibre Content serverに接続するため、`calibre-server` を起動する手順は不要です。\n\nWindowsではDefender Controlled Folder Access等の影響で書き込みが失敗する場合があります。\n`WinError 2/5` などのパス/アクセス系エラーが出る場合は、Calibreライブラリフォルダや実行バイナリを許可リストに追加してください。\n\n## 安全モデル\n\n- 入力はJSONL（1行=1更新）\n- `id` 必須\n- デフォルトはdry-run（`--apply` 指定時のみ書き込み）\n\n## ライブラリ横断処理（ターン分割）\n\n長時間処理はターン分割で実行し、チャット継続性を優先します。\n\n- 開始ターン:\n - scopeと出力契約を含む自己完結したtaskを作る\n - OpenClaw `sessions_spawn`を直接呼んで解析を委譲\n - `scripts/run_state.mjs` で実行状態を記録\n- 完了ターン: 完了通知後、`scripts/handle_completion.mjs` で状態を片付けて結果を提示\n- state保存先: `state/runs.json`\n\n### Subagent runtime\n\n`TOOLS.md` の `calibre-meta` 行はmodel・thinkingのローカル既定値です。\n\n- OpenClaw `sessions_spawn`を直接呼ぶ。\n- toolが公開する現在のschemaに従い、別の共通payloadを生成しない。\n- mainだけが候補の採否、dry-run、apply、ユーザー応答を担当する。\n\n## 認証キャッシュ（初回保存）\n\n初回だけ認証情報を保存しておくと、以後は `--username` / `--password-env` を省略できます。\n\n```bash\ncat references/changes.example.jsonl | node scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --save-auth\n```\n\n平文パスワードも保存したい場合（非推奨）は次を追加:\n\n```bash\n--save-plain-password\n```\n\n## クイックテスト（dry-run）\n\n```bash\ncat references/changes.example.jsonl | node scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\"\n```\n\n`--with-library` を省略したい場合は、先に `CALIBRE_WITH_LIBRARY` などを設定してください。\n\nFile v1.0.5:_meta.json\n\n{\n \"ownerId\": \"kn747bx1r2jrbbyca61v6k06397zy93t\",\n \"slug\": \"calibre-metadata-apply\",\n \"version\": \"1.0.5\",\n \"publishedAt\": 1785224881710\n}\n\nFile v1.0.5:skill-card.md\n\n## Description:
\nEdit Calibre title, authors, series, tags, dates, comments, and analysis metadata with dry-run/apply gates.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[nextaltair](https://clawhub.ai/user/nextaltair)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and library maintainers use this skill to update Calibre book metadata such as titles, authors, series, tags, dates, comments, and analysis fields with confirmation, dry-run, and apply steps.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: The skill can modify Calibre metadata and requires access to a Calibre library.
\nMitigation: Keep credentials in environment variables, review dry-runs before apply, and apply changes only after explicit user approval.
\nRisk: The skill may read document content, use web evidence, or delegate extracted evidence for heavy proposal generation.
\nMitigation: Keep analysis local unless the user explicitly approves sharing book excerpts or evidence with a subagent.
\nRisk: Low-confidence or conflicting metadata proposals could overwrite useful existing fields if applied without review.
\nMitigation: Use the documented pending-review flow for unresolved items and apply only approved, high-confidence fields.
\n\n\n## Reference(s):
\n- [ClawHub skill page](https://clawhub.ai/nextaltair/skills/calibre-metadata-apply)
\n- [Publisher profile](https://clawhub.ai/user/nextaltair)
\n\n\n## Skill Output:
\n**Output Type(s):** [text, markdown, code, shell commands, configuration, guidance]
\n**Output Format:** [Markdown guidance with JSONL change plans and shell commands]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Requires node, calibredb, CALIBRE_PASSWORD, and explicit user approval before applying metadata writes.]
\n\n## Skill Version(s):
\n1.0.5 (source: server release evidence)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nArchive v1.0.4: 7 files, 17557 bytes\n\nFiles: README.md (6218b), scripts/calibredb_apply.mjs (18121b), scripts/handle_completion.mjs (1989b), scripts/run_state.mjs (3259b), skill-card.md (2322b), SKILL.md (10536b), _meta.json (141b)\n\nFile v1.0.4:SKILL.md\n\n---\nname: calibre-metadata-apply\ndescription: Primary skill for Calibre metadata edits (write operations) over a running Content server. Use ONLY when the user explicitly requests changing/editing/fixing title/authors/series/series_index/tags/publisher/pubdate/languages. Never use for read-only lookups, even if an ID is mentioned.\nmetadata: {\"openclaw\":{\"requires\":{\"bins\":[\"node\",\"calibredb\"],\"env\":[\"CALIBRE_PASSWORD\"]},\"optionalBins\":[\"pdffonts\"],\"optionalEnv\":[\"CALIBRE_USERNAME\"],\"primaryEnv\":\"CALIBRE_PASSWORD\",\"dependsOnSkills\":[\"subagent-spawn-command-builder\"],\"localWrites\":[\"skills/calibre-metadata-apply/state/runs.json\"],\"modifiesRemoteData\":[\"calibre:metadata\"]}}\n---\n\n# calibre-metadata-apply\n\nA skill for updating metadata of existing Calibre books.\n\n## Skill selection contract (strict)\n\n- If the user intent is metadata edit/fix/update, this skill is mandatory.\n- If the request mentions an ID **together with edit/fix/update intent** (e.g. `ID1011 タイトル修正`, `ID1011 のタイトルを直して`), this skill is mandatory.\n- 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`.\n- `calibre-catalog-read` must not be used for those edit intents.\n\nUse this skill when the user asks any of:\n- \"ID指定でタイトル修正\"\n- \"メタデータ編集\"\n- `title/authors/series/series_index/tags/publisher/pubdate/languages` updates\n\nDo NOT use this skill for:\n- Read-only lookups (e.g. \"ID 1021 を確認して\", \"ID 1021 の情報を見せて\", \"show me book 1021\")\n- Checking what metadata a book currently has without intent to change it\n- Those must use `calibre-catalog-read`\n\n## Requirements\n\n- `calibredb` must be available on PATH in the runtime environment\n- `subagent-spawn-command-builder` installed (for spawn payload generation)\n- `pdffonts` is optional/recommended for PDF evidence checks\n- Reachable Calibre Content server URL\n - `http://HOST:PORT/#LIBRARY_ID`\n - If `LIBRARY_ID` is unknown, use `#-` once to list available IDs on the server.\n- `--with-library` can be omitted only when one of these is configured:\n - env: `CALIBRE_WITH_LIBRARY` or `CALIBRE_LIBRARY_URL` or `CALIBRE_CONTENT_SERVER_URL`\n - optional library id completion: `CALIBRE_LIBRARY_ID`\n- Read the \"Calibre Content Server\" section of TOOLS.md for the correct `--with-library` URL.\n- Host failover (IP change resilience):\n - Optional env: `CALIBRE_SERVER_HOSTS=host1,host2,...`\n - Script auto-tries candidates, including WSL host-side `nameserver` from `/etc/resolv.conf`.\n- If authentication is enabled, prefer `/home/altair/.openclaw/.env`:\n - `CALIBRE_USERNAME=`\n - `CALIBRE_PASSWORD=`\n- Auth scheme policy for this workflow:\n - Non-SSL deployment assumes **Digest** authentication.\n - Do not pass auth mode arguments such as `--auth-mode` / `--auth-scheme`.\n- Pass `--password-env CALIBRE_PASSWORD` (username auto-loads from env)\n- You can still override explicitly with `--username `.\n\n## Supported fields\n\n### Direct fields (`set_metadata --field`)\n- `title`\n- `title_sort`\n- `authors` (string with `&` or array)\n- `author_sort`\n- `series`\n- `series_index`\n- `tags` (string or array)\n- `publisher`\n- `pubdate` (`YYYY-MM-DD`)\n- `languages`\n- `comments`\n\n### Helper fields\n- `comments_html` (OC marker block upsert)\n- `analysis` (auto-generates analysis HTML for comments)\n- `analysis_tags` (adds tags)\n- `tags_merge` (default `true`)\n- `tags_remove` (remove specific tags after merge)\n\n## Required execution flow\n\n### A. Target confirmation (mandatory)\n1. Run read-only lookup to narrow candidates\n2. Show `id,title,authors,series,series_index`\n3. Get user confirmation for final target IDs\n4. Build JSONL using only confirmed IDs\n\n### B. Proposal synthesis (when metadata is missing)\n1. Collect evidence from file extraction + web sources\n2. Show one merged proposal table with:\n - `candidate`, `source`, `confidence (high|medium|low)`\n - `title_sort_candidate`, `author_sort_candidate`\n3. Get user decision:\n - `approve all`\n - `approve only: `\n - `reject: `\n - `edit: =`\n4. Apply only approved/finalized fields\n5. If confidence is low or sources conflict, keep fields empty\n\n### C. Apply\n1. Run dry-run first (mandatory)\n2. Run `--apply` only after explicit user approval\n3. Re-read and report final values\n\n## Analysis worker policy\n\n- Use `subagent-spawn-command-builder` to generate `sessions_spawn` payload for heavy candidate generation\n - `task` is required.\n - Profile should include model/thinking/timeout/cleanup for this workflow.\n- Use lightweight subagent model for analysis (avoid main heavy model)\n- Keep final decisions + dry-run/apply in main\n\n## Data flow disclosure\n\n- Local execution:\n - Build `calibredb set_metadata` commands from JSONL.\n - Read/write local state files (`state/runs.json`).\n- Subagent execution (optional for heavy candidate generation):\n - Uses `sessions_spawn` via `subagent-spawn-command-builder`.\n - Text/metadata sent to subagent can reach model endpoints configured by runtime profile.\n- Remote write:\n - `calibredb set_metadata` updates metadata on the target Calibre Content server.\n\nSecurity rules:\n- Prefer env-based password (`--password-env CALIBRE_PASSWORD`) over inline `--password`.\n- If user does not want external model/subagent processing, keep flow local and skip subagent orchestration.\n- In agent/chat execution, do not call `calibredb` directly for edit operations.\n - Always execute `node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs`.\n- Never run `calibre-server` from this skill.\n - This workflow always targets an already-running Calibre Content server.\n\n## Connection bootstrap (mandatory)\n\n- Do not ask the user for `--with-library` first.\n- First, execute using saved defaults (env) with no explicit `--with-library`.\n - Scripts auto-load `.env` and resolve `CALIBRE_WITH_LIBRARY` / `CALIBRE_CONTENT_SERVER_URL`.\n- Ask user for URL only when command output shows unresolved connection, such as:\n - `missing --with-library`\n - `unable to resolve usable --with-library`\n - repeated connection failures for all candidates\n\n## Long-run turn-split policy (library-wide)\n\nFor library-wide heavy processing, always use turn-split execution.\n\n## Unknown-document recovery flow (M3)\n\nBatch sizing rule:\n- Keep each unknown-document batch small enough to show full row-by-row results in chat (no representative sampling).\n- If unresolved items remain, stop and wait for explicit user instruction to start the next batch.\n\n### User intervention checkpoints (fixed)\n\n1. **Light pass (metadata-only)**\n - Always run this stage by default (no extra user instruction required)\n - Analyze existing metadata only (no file content read)\n - Present a table to user:\n - current file/title\n - recommended title/metadata\n - confidence/evidence summary\n - Stop and wait for user instruction before any deeper stage\n\n2. **On user request: page-1 pass**\n - Read only the first page and refine proposals\n - Report delta from light pass\n\n3. **If still uncertain: deep pass**\n - Read first 5 pages + last 5 pages\n - Add web evidence search\n - Produce finalized proposal with confidence + rationale\n\n4. **Approval gate**\n - Show detailed findings and request explicit approval before apply\n\n### Pending and unsupported handling\n\n- Use `pending-review` tag for unresolved/hold items.\n- If document is unresolved in current flow, do not force metadata guesses.\n - Tag with `pending-review` and keep for follow-up investigation.\n\n### Diff report format (for unknown batch runs)\n\nReturn full results (not samples):\n- execution summary (target/changed/pending/skipped/error)\n- full changed list with `id` + key before/after fields\n- full pending list with `id` + reason\n- full error list with `id` + error summary\n- confidence must be expressed as `high|medium|low`\n\n### Runtime artifact policy\n\n- Keep run-state and temporary artifacts only while a run is active.\n- On successful completion, remove per-run state/artifacts.\n- On failure, keep minimal artifacts only for retry/debug, then clean up after resolution.\n\n### Internal orchestration (recommended)\n\n- Use lightweight subagent for all analysis stages\n- Keep apply decisions in main session\n- Persist run state for each stage in `state/runs.json`\n\n### Turn 1 (start)\n1. Main defines scope\n2. Main generates spawn payload via `subagent-spawn-command-builder` (profile example: `calibre-meta`), then calls `sessions_spawn`\n3. Save `run_id/session_key/task` via `scripts/run_state.mjs upsert`\n4. Immediately tell the user this is a subagent job and state the execution model used for analysis\n5. Reply with \"analysis started\" and keep normal chat responsive\n\n### Turn 2 (completion)\n1. Receive subagent completion notice\n2. Save result JSON\n3. Complete state handling via `scripts/handle_completion.mjs --run-id ... --result-json ...`\n4. Return summarized proposal (apply only when needed)\n\nRun state file:\n- `state/runs.json`\n\n## PDF extraction policy\n\n1. Try `ebook-convert` first\n2. If empty/failed, fallback to `pdftotext`\n3. If both fail, switch to web-evidence-first mode\n\n## Sort reading policy\n\n- Use user-configured `reading_script` for Japanese/non-Latin sort fields\n - `katakana` / `hiragana` / `latin`\n- Ask once on first use, then reuse for the session\n- Default policy is full reading (no truncation)\n- Read the \"Calibre Content Server\" section of TOOLS.md for the configured `reading_script` value; pass it as a CLI argument when needed.\n\n## Usage\n\nDry-run:\n\n```bash\ncat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --lang ja\n```\n\nDry-run (when default library is preconfigured via env/config):\n\n```bash\ncat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \\\n --password-env CALIBRE_PASSWORD \\\n --lang ja\n```\n\nApply:\n\n```bash\ncat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --apply\n```\n\n## Do not\n\n- Do not run direct `--apply` using ambiguous title matches only\n- Do not include unconfirmed IDs in apply payload\n- Do not auto-fill low-confidence candidates without explicit confirmation\n- Do not start a local server with guessed path like `~/Calibre Library`\n\nFile v1.0.4:README.md\n\n# calibre-metadata-apply\n\n`calibredb` を使って、既存Calibre書籍のメタデータを更新するスキルです。\n\n## このスキルの目的\n\nこのスキルは、Calibreライブラリのメタデータ運用を\n**「安全に・継続的に・監査可能に」回す** ための実務スキルです。\n\n### 1) 何を解決するか\n\n- 手作業で崩れやすいメタデータ整備（title/authors/publisher/pubdate/tags/sort）を定型化\n- 1冊編集とライブラリ横断編集を同じ運用ルールで実施\n- 長時間ジョブでもチャットを止めずに進行（ターン分割）\n\n### 2) 何を自動化するか\n\n- 1冊単位の確定編集（確認→dry-run→apply→検証）\n- ライブラリ横断の推定タグ付与（本文ではなく既存メタデータのみを利用）\n- 高確信候補の自動適用と、低確信候補の保留\n\n### 3) 何をしないか（境界）\n\n- 曖昧な対象に対する即時apply\n- 根拠が弱い候補の無条件上書き\n- 本文解析が必要な重処理をmainターンで同期実行\n\n### 4) 想定ユースケース\n\n- 「ID指定で論文書誌を修正したい」\n- 「マニュアルらしい本に `マニュアル/Manual` を一括付与したい」\n- 「論文らしい本を横断抽出して `論文` タグを付けたい」\n\n### 5) 運用ポリシー（要点）\n\n- 高確信な提案のみ自動適用\n- 低確信・衝突ケースは保留/再処理\n- 保留は `pending-review` タグを付与して管理\n- confidence表現は `high/medium/low` に統一\n- 長時間処理はターン分割（開始ACK→完了報告）\n- 実行中の状態/一時ファイルは完了時に削除（失敗時のみ最小限保持）\n\n## セットアップ\n\n1. このスキルを実行する環境にCalibreをインストールする\n - 必須: `calibredb`\n2. PDF調査用に `pdffonts` を使えるようにする（例: `poppler-utils`）\n3. `subagent-spawn-command-builder` を導入する（spawn payload生成に使用）\n\n```bash\nnpx clawhub@latest install subagent-spawn-command-builder\npnpm dlx clawhub@latest install subagent-spawn-command-builder\n```\n\n4. `calibredb` と `pdffonts` が `PATH` で実行できることを確認する\n5. Calibre Content server に到達できることを確認する\n6. `--with-library` は次の形式で指定する\n - `http://HOST:PORT/#LIBRARY_ID`\n - localhost前提にしない（明示的なHOST:PORTを使う）\n - 省略する場合は以下のどれかを事前設定する\n - env: `CALIBRE_WITH_LIBRARY` / `CALIBRE_LIBRARY_URL` / `CALIBRE_CONTENT_SERVER_URL`\n - config: `~/.config/calibre-metadata-apply/config.json` の `with_library`\n - URLに`#LIBRARY_ID`が無い場合は `CALIBRE_LIBRARY_ID` か config `library_id` で補完可能\n - IP変更対策:\n - `CALIBRE_SERVER_HOSTS=host1,host2,...` を設定すると候補を順に試行\n - WSLでは `/etc/resolv.conf` の `nameserver` も自動候補に追加\n - `LIBRARY_ID` が不明な場合は `#-` で一覧確認できる\n - 例: `calibredb list --with-library \"http://HOST:PORT/#-\" --username ... --password ...`\n7. 認証が有効な場合は次を指定する\n - `--username `\n - `--password-env ` または `--password `\n - 認証方式は非SSL運用前提でDigest固定(自動)とし、`--auth-mode` / `--auth-scheme` は使わない\n8. 認証情報を保存して再利用したい場合は `--save-auth` を使う\n - 既定保存先: `~/.config/calibre-metadata-apply/auth.json`\n - 既定では `username` と `password_env` を保存\n - 平文パスワードも保存する場合のみ `--save-plain-password` を追加\n\n### ユーザーが先に実行すること（例: Ubuntu/WSL）\n\n```bash\nsudo apt update\nsudo apt install -y calibre poppler-utils\n```\n\n## 重要\n\nOpenClawが入っているだけでは不十分です。実行環境側に `calibredb` が必要です。\nチャット実行時は `calibredb` 直接実行ではなく、必ず `node scripts/calibredb_apply.mjs` を使ってください。\nこの運用では既存のCalibre Content serverに接続するため、`calibre-server` を起動する手順は不要です。\n\nWindowsではDefender Controlled Folder Access等の影響で書き込みが失敗する場合があります。\n`WinError 2/5` などのパス/アクセス系エラーが出る場合は、Calibreライブラリフォルダや実行バイナリを許可リストに追加してください。\n\n## 安全モデル\n\n- 入力はJSONL（1行=1更新）\n- `id` 必須\n- デフォルトはdry-run（`--apply` 指定時のみ書き込み）\n\n## ライブラリ横断処理（ターン分割）\n\n長時間処理はターン分割で実行し、チャット継続性を優先します。\n\n- 開始ターン:\n - `subagent-spawn-command-builder` で `sessions_spawn` payloadを生成（例: `profile=calibre-meta`）\n - 生成payloadで軽量subagentに解析を委譲\n - `scripts/run_state.mjs` で実行状態を記録\n- 完了ターン: 完了通知後、`scripts/handle_completion.mjs` で状態を片付けて結果を提示\n- state保存先: `state/runs.json`\n\n### `spawn-profiles.json` に追加する例（`calibre-meta`）\n\n```json\n{\n \"profiles\": {\n \"calibre-meta\": {\n \"model\": \"openrouter/qwen/qwen3-next-80b-a3b-instruct\",\n \"thinking\": \"low\",\n \"runTimeoutSeconds\": 300,\n \"cleanup\": \"keep\"\n }\n }\n}\n```\n\n## 認証キャッシュ（初回保存）\n\n初回だけ認証情報を保存しておくと、以後は `--username` / `--password-env` を省略できます。\n\n```bash\ncat references/changes.example.jsonl | node scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --save-auth\n```\n\n平文パスワードも保存したい場合（非推奨）は次を追加:\n\n```bash\n--save-plain-password\n```\n\n## クイックテスト（dry-run）\n\n```bash\ncat references/changes.example.jsonl | node scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\"\n```\n\n`--with-library` を省略したい場合は、先に `CALIBRE_WITH_LIBRARY` などを設定してください。\n\nFile v1.0.4:_meta.json\n\n{\n \"ownerId\": \"kn747bx1r2jrbbyca61v6k06397zy93t\",\n \"slug\": \"calibre-metadata-apply\",\n \"version\": \"1.0.4\",\n \"publishedAt\": 1775299872595\n}\n\nFile v1.0.4:skill-card.md\n\n## Description:
\nPrimary skill for applying confirmed Calibre metadata edits to an existing Content server while avoiding read-only lookup workflows.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[nextaltair](https://clawhub.ai/user/nextaltair)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and library operators use this skill to update existing Calibre book metadata after confirming target IDs, dry-running changes, and approving writes. It supports single-book fixes and library-wide metadata maintenance where low-confidence candidates remain pending for review.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: The skill can modify metadata on a target Calibre Content server.
\nMitigation: Use confirmed IDs, run dry-runs first, require explicit approval before writes, and re-read final values after applying changes.
\nRisk: Credentials or book metadata may be exposed if handled carelessly during execution.
\nMitigation: Prefer CALIBRE_PASSWORD over plaintext passwords and skip subagent processing when book metadata should remain local.
\nRisk: Generated comments_html or analysis content may introduce incorrect metadata notes.
\nMitigation: Review comments_html and analysis content before approving any write operation.
\n\n\n## Reference(s):
\n- [ClawHub Skill Page](https://clawhub.ai/nextaltair/calibre-metadata-apply)
\n- [README](artifact/README.md)
\n- [Skill Definition](artifact/SKILL.md)
\n\n\n## Skill Output:
\n**Output Type(s):** [Guidance, Markdown, Shell commands, Configuration, JSONL]
\n**Output Format:** [Markdown guidance with shell commands and JSONL change payloads]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [Default workflow requires confirmed book IDs, dry-run before apply, and explicit approval for writes.]
\n\n## Skill Version(s):
\n1.0.4 (source: server release metadata and release changelog)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nArchive v1.0.3: 6 files, 16094 bytes\n\nFiles: README.md (6218b), scripts/calibredb_apply.mjs (18121b), scripts/handle_completion.mjs (1989b), scripts/run_state.mjs (3259b), SKILL.md (10015b), _meta.json (141b)\n\nFile v1.0.3:SKILL.md\n\n---\nname: calibre-metadata-apply\ndescription: 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.\nmetadata: {\"openclaw\":{\"requires\":{\"bins\":[\"node\",\"calibredb\"],\"env\":[\"CALIBRE_PASSWORD\"]},\"optionalBins\":[\"pdffonts\"],\"optionalEnv\":[\"CALIBRE_USERNAME\"],\"primaryEnv\":\"CALIBRE_PASSWORD\",\"dependsOnSkills\":[\"subagent-spawn-command-builder\"],\"localWrites\":[\"skills/calibre-metadata-apply/state/runs.json\"],\"modifiesRemoteData\":[\"calibre:metadata\"]}}\n---\n\n# calibre-metadata-apply\n\nA skill for updating metadata of existing Calibre books.\n\n## Skill selection contract (strict)\n\n- If the user intent is metadata edit/fix/update, this skill is mandatory.\n- If the request mentions ID-based title fix (e.g. `ID1011 タイトル修正`), this skill is mandatory.\n- `calibre-catalog-read` must not be used for those edit intents.\n\nUse this skill when the user asks any of:\n- \"ID指定でタイトル修正\"\n- \"メタデータ編集\"\n- `title/authors/series/series_index/tags/publisher/pubdate/languages` updates\n\nDo NOT route those requests to `calibre-catalog-read`.\n\n## Requirements\n\n- `calibredb` must be available on PATH in the runtime environment\n- `subagent-spawn-command-builder` installed (for spawn payload generation)\n- `pdffonts` is optional/recommended for PDF evidence checks\n- Reachable Calibre Content server URL\n - `http://HOST:PORT/#LIBRARY_ID`\n - If `LIBRARY_ID` is unknown, use `#-` once to list available IDs on the server.\n- `--with-library` can be omitted only when one of these is configured:\n - env: `CALIBRE_WITH_LIBRARY` or `CALIBRE_LIBRARY_URL` or `CALIBRE_CONTENT_SERVER_URL`\n - optional library id completion: `CALIBRE_LIBRARY_ID`\n- Read the \"Calibre Content Server\" section of TOOLS.md for the correct `--with-library` URL.\n- Host failover (IP change resilience):\n - Optional env: `CALIBRE_SERVER_HOSTS=host1,host2,...`\n - Script auto-tries candidates, including WSL host-side `nameserver` from `/etc/resolv.conf`.\n- If authentication is enabled, prefer `/home/altair/.openclaw/.env`:\n - `CALIBRE_USERNAME=`\n - `CALIBRE_PASSWORD=`\n- Auth scheme policy for this workflow:\n - Non-SSL deployment assumes **Digest** authentication.\n - Do not pass auth mode arguments such as `--auth-mode` / `--auth-scheme`.\n- Pass `--password-env CALIBRE_PASSWORD` (username auto-loads from env)\n- You can still override explicitly with `--username `.\n\n## Supported fields\n\n### Direct fields (`set_metadata --field`)\n- `title`\n- `title_sort`\n- `authors` (string with `&` or array)\n- `author_sort`\n- `series`\n- `series_index`\n- `tags` (string or array)\n- `publisher`\n- `pubdate` (`YYYY-MM-DD`)\n- `languages`\n- `comments`\n\n### Helper fields\n- `comments_html` (OC marker block upsert)\n- `analysis` (auto-generates analysis HTML for comments)\n- `analysis_tags` (adds tags)\n- `tags_merge` (default `true`)\n- `tags_remove` (remove specific tags after merge)\n\n## Required execution flow\n\n### A. Target confirmation (mandatory)\n1. Run read-only lookup to narrow candidates\n2. Show `id,title,authors,series,series_index`\n3. Get user confirmation for final target IDs\n4. Build JSONL using only confirmed IDs\n\n### B. Proposal synthesis (when metadata is missing)\n1. Collect evidence from file extraction + web sources\n2. Show one merged proposal table with:\n - `candidate`, `source`, `confidence (high|medium|low)`\n - `title_sort_candidate`, `author_sort_candidate`\n3. Get user decision:\n - `approve all`\n - `approve only: `\n - `reject: `\n - `edit: =`\n4. Apply only approved/finalized fields\n5. If confidence is low or sources conflict, keep fields empty\n\n### C. Apply\n1. Run dry-run first (mandatory)\n2. Run `--apply` only after explicit user approval\n3. Re-read and report final values\n\n## Analysis worker policy\n\n- Use `subagent-spawn-command-builder` to generate `sessions_spawn` payload for heavy candidate generation\n - `task` is required.\n - Profile should include model/thinking/timeout/cleanup for this workflow.\n- Use lightweight subagent model for analysis (avoid main heavy model)\n- Keep final decisions + dry-run/apply in main\n\n## Data flow disclosure\n\n- Local execution:\n - Build `calibredb set_metadata` commands from JSONL.\n - Read/write local state files (`state/runs.json`).\n- Subagent execution (optional for heavy candidate generation):\n - Uses `sessions_spawn` via `subagent-spawn-command-builder`.\n - Text/metadata sent to subagent can reach model endpoints configured by runtime profile.\n- Remote write:\n - `calibredb set_metadata` updates metadata on the target Calibre Content server.\n\nSecurity rules:\n- Prefer env-based password (`--password-env CALIBRE_PASSWORD`) over inline `--password`.\n- If user does not want external model/subagent processing, keep flow local and skip subagent orchestration.\n- In agent/chat execution, do not call `calibredb` directly for edit operations.\n - Always execute `node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs`.\n- Never run `calibre-server` from this skill.\n - This workflow always targets an already-running Calibre Content server.\n\n## Connection bootstrap (mandatory)\n\n- Do not ask the user for `--with-library` first.\n- First, execute using saved defaults (env) with no explicit `--with-library`.\n - Scripts auto-load `.env` and resolve `CALIBRE_WITH_LIBRARY` / `CALIBRE_CONTENT_SERVER_URL`.\n- Ask user for URL only when command output shows unresolved connection, such as:\n - `missing --with-library`\n - `unable to resolve usable --with-library`\n - repeated connection failures for all candidates\n\n## Long-run turn-split policy (library-wide)\n\nFor library-wide heavy processing, always use turn-split execution.\n\n## Unknown-document recovery flow (M3)\n\nBatch sizing rule:\n- Keep each unknown-document batch small enough to show full row-by-row results in chat (no representative sampling).\n- If unresolved items remain, stop and wait for explicit user instruction to start the next batch.\n\n### User intervention checkpoints (fixed)\n\n1. **Light pass (metadata-only)**\n - Always run this stage by default (no extra user instruction required)\n - Analyze existing metadata only (no file content read)\n - Present a table to user:\n - current file/title\n - recommended title/metadata\n - confidence/evidence summary\n - Stop and wait for user instruction before any deeper stage\n\n2. **On user request: page-1 pass**\n - Read only the first page and refine proposals\n - Report delta from light pass\n\n3. **If still uncertain: deep pass**\n - Read first 5 pages + last 5 pages\n - Add web evidence search\n - Produce finalized proposal with confidence + rationale\n\n4. **Approval gate**\n - Show detailed findings and request explicit approval before apply\n\n### Pending and unsupported handling\n\n- Use `pending-review` tag for unresolved/hold items.\n- If document is unresolved in current flow, do not force metadata guesses.\n - Tag with `pending-review` and keep for follow-up investigation.\n\n### Diff report format (for unknown batch runs)\n\nReturn full results (not samples):\n- execution summary (target/changed/pending/skipped/error)\n- full changed list with `id` + key before/after fields\n- full pending list with `id` + reason\n- full error list with `id` + error summary\n- confidence must be expressed as `high|medium|low`\n\n### Runtime artifact policy\n\n- Keep run-state and temporary artifacts only while a run is active.\n- On successful completion, remove per-run state/artifacts.\n- On failure, keep minimal artifacts only for retry/debug, then clean up after resolution.\n\n### Internal orchestration (recommended)\n\n- Use lightweight subagent for all analysis stages\n- Keep apply decisions in main session\n- Persist run state for each stage in `state/runs.json`\n\n### Turn 1 (start)\n1. Main defines scope\n2. Main generates spawn payload via `subagent-spawn-command-builder` (profile example: `calibre-meta`), then calls `sessions_spawn`\n3. Save `run_id/session_key/task` via `scripts/run_state.mjs upsert`\n4. Immediately tell the user this is a subagent job and state the execution model used for analysis\n5. Reply with \"analysis started\" and keep normal chat responsive\n\n### Turn 2 (completion)\n1. Receive subagent completion notice\n2. Save result JSON\n3. Complete state handling via `scripts/handle_completion.mjs --run-id ... --result-json ...`\n4. Return summarized proposal (apply only when needed)\n\nRun state file:\n- `state/runs.json`\n\n## PDF extraction policy\n\n1. Try `ebook-convert` first\n2. If empty/failed, fallback to `pdftotext`\n3. If both fail, switch to web-evidence-first mode\n\n## Sort reading policy\n\n- Use user-configured `reading_script` for Japanese/non-Latin sort fields\n - `katakana` / `hiragana` / `latin`\n- Ask once on first use, then reuse for the session\n- Default policy is full reading (no truncation)\n- Read the \"Calibre Content Server\" section of TOOLS.md for the configured `reading_script` value; pass it as a CLI argument when needed.\n\n## Usage\n\nDry-run:\n\n```bash\ncat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --lang ja\n```\n\nDry-run (when default library is preconfigured via env/config):\n\n```bash\ncat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \\\n --password-env CALIBRE_PASSWORD \\\n --lang ja\n```\n\nApply:\n\n```bash\ncat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --apply\n```\n\n## Do not\n\n- Do not run direct `--apply` using ambiguous title matches only\n- Do not include unconfirmed IDs in apply payload\n- Do not auto-fill low-confidence candidates without explicit confirmation\n- Do not start a local server with guessed path like `~/Calibre Library`\n\nFile v1.0.3:README.md\n\n# calibre-metadata-apply\n\n`calibredb` を使って、既存Calibre書籍のメタデータを更新するスキルです。\n\n## このスキルの目的\n\nこのスキルは、Calibreライブラリのメタデータ運用を\n**「安全に・継続的に・監査可能に」回す** ための実務スキルです。\n\n### 1) 何を解決するか\n\n- 手作業で崩れやすいメタデータ整備（title/authors/publisher/pubdate/tags/sort）を定型化\n- 1冊編集とライブラリ横断編集を同じ運用ルールで実施\n- 長時間ジョブでもチャットを止めずに進行（ターン分割）\n\n### 2) 何を自動化するか\n\n- 1冊単位の確定編集（確認→dry-run→apply→検証）\n- ライブラリ横断の推定タグ付与（本文ではなく既存メタデータのみを利用）\n- 高確信候補の自動適用と、低確信候補の保留\n\n### 3) 何をしないか（境界）\n\n- 曖昧な対象に対する即時apply\n- 根拠が弱い候補の無条件上書き\n- 本文解析が必要な重処理をmainターンで同期実行\n\n### 4) 想定ユースケース\n\n- 「ID指定で論文書誌を修正したい」\n- 「マニュアルらしい本に `マニュアル/Manual` を一括付与したい」\n- 「論文らしい本を横断抽出して `論文` タグを付けたい」\n\n### 5) 運用ポリシー（要点）\n\n- 高確信な提案のみ自動適用\n- 低確信・衝突ケースは保留/再処理\n- 保留は `pending-review` タグを付与して管理\n- confidence表現は `high/medium/low` に統一\n- 長時間処理はターン分割（開始ACK→完了報告）\n- 実行中の状態/一時ファイルは完了時に削除（失敗時のみ最小限保持）\n\n## セットアップ\n\n1. このスキルを実行する環境にCalibreをインストールする\n - 必須: `calibredb`\n2. PDF調査用に `pdffonts` を使えるようにする（例: `poppler-utils`）\n3. `subagent-spawn-command-builder` を導入する（spawn payload生成に使用）\n\n```bash\nnpx clawhub@latest install subagent-spawn-command-builder\npnpm dlx clawhub@latest install subagent-spawn-command-builder\n```\n\n4. `calibredb` と `pdffonts` が `PATH` で実行できることを確認する\n5. Calibre Content server に到達できることを確認する\n6. `--with-library` は次の形式で指定する\n - `http://HOST:PORT/#LIBRARY_ID`\n - localhost前提にしない（明示的なHOST:PORTを使う）\n - 省略する場合は以下のどれかを事前設定する\n - env: `CALIBRE_WITH_LIBRARY` / `CALIBRE_LIBRARY_URL` / `CALIBRE_CONTENT_SERVER_URL`\n - config: `~/.config/calibre-metadata-apply/config.json` の `with_library`\n - URLに`#LIBRARY_ID`が無い場合は `CALIBRE_LIBRARY_ID` か config `library_id` で補完可能\n - IP変更対策:\n - `CALIBRE_SERVER_HOSTS=host1,host2,...` を設定すると候補を順に試行\n - WSLでは `/etc/resolv.conf` の `nameserver` も自動候補に追加\n - `LIBRARY_ID` が不明な場合は `#-` で一覧確認できる\n - 例: `calibredb list --with-library \"http://HOST:PORT/#-\" --username ... --password ...`\n7. 認証が有効な場合は次を指定する\n - `--username `\n - `--password-env ` または `--password `\n - 認証方式は非SSL運用前提でDigest固定(自動)とし、`--auth-mode` / `--auth-scheme` は使わない\n8. 認証情報を保存して再利用したい場合は `--save-auth` を使う\n - 既定保存先: `~/.config/calibre-metadata-apply/auth.json`\n - 既定では `username` と `password_env` を保存\n - 平文パスワードも保存する場合のみ `--save-plain-password` を追加\n\n### ユーザーが先に実行すること（例: Ubuntu/WSL）\n\n```bash\nsudo apt update\nsudo apt install -y calibre poppler-utils\n```\n\n## 重要\n\nOpenClawが入っているだけでは不十分です。実行環境側に `calibredb` が必要です。\nチャット実行時は `calibredb` 直接実行ではなく、必ず `node scripts/calibredb_apply.mjs` を使ってください。\nこの運用では既存のCalibre Content serverに接続するため、`calibre-server` を起動する手順は不要です。\n\nWindowsではDefender Controlled Folder Access等の影響で書き込みが失敗する場合があります。\n`WinError 2/5` などのパス/アクセス系エラーが出る場合は、Calibreライブラリフォルダや実行バイナリを許可リストに追加してください。\n\n## 安全モデル\n\n- 入力はJSONL（1行=1更新）\n- `id` 必須\n- デフォルトはdry-run（`--apply` 指定時のみ書き込み）\n\n## ライブラリ横断処理（ターン分割）\n\n長時間処理はターン分割で実行し、チャット継続性を優先します。\n\n- 開始ターン:\n - `subagent-spawn-command-builder` で `sessions_spawn` payloadを生成（例: `profile=calibre-meta`）\n - 生成payloadで軽量subagentに解析を委譲\n - `scripts/run_state.mjs` で実行状態を記録\n- 完了ターン: 完了通知後、`scripts/handle_completion.mjs` で状態を片付けて結果を提示\n- state保存先: `state/runs.json`\n\n### `spawn-profiles.json` に追加する例（`calibre-meta`）\n\n```json\n{\n \"profiles\": {\n \"calibre-meta\": {\n \"model\": \"openrouter/qwen/qwen3-next-80b-a3b-instruct\",\n \"thinking\": \"low\",\n \"runTimeoutSeconds\": 300,\n \"cleanup\": \"keep\"\n }\n }\n}\n```\n\n## 認証キャッシュ（初回保存）\n\n初回だけ認証情報を保存しておくと、以後は `--username` / `--password-env` を省略できます。\n\n```bash\ncat references/changes.example.jsonl | node scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --save-auth\n```\n\n平文パスワードも保存したい場合（非推奨）は次を追加:\n\n```bash\n--save-plain-password\n```\n\n## クイックテスト（dry-run）\n\n```bash\ncat references/changes.example.jsonl | node scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\"\n```\n\n`--with-library` を省略したい場合は、先に `CALIBRE_WITH_LIBRARY` などを設定してください。\n\nFile v1.0.3:_meta.json\n\n{\n \"ownerId\": \"kn747bx1r2jrbbyca61v6k06397zy93t\",\n \"slug\": \"calibre-metadata-apply\",\n \"version\": \"1.0.3\",\n \"publishedAt\": 1775276582229\n}\n\nArchive v1.0.2: 6 files, 16812 bytes\n\nFiles: README.md (6218b), scripts/calibredb_apply.mjs (20459b), scripts/handle_completion.mjs (1989b), scripts/run_state.mjs (3259b), SKILL.md (10318b), _meta.json (141b)\n\nFile v1.0.2:SKILL.md\n\n---\nname: calibre-metadata-apply\ndescription: 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.\nmetadata: {\"openclaw\":{\"requires\":{\"bins\":[\"node\",\"calibredb\"],\"env\":[\"CALIBRE_PASSWORD\"]},\"optionalBins\":[\"pdffonts\"],\"optionalEnv\":[\"CALIBRE_USERNAME\"],\"primaryEnv\":\"CALIBRE_PASSWORD\",\"dependsOnSkills\":[\"subagent-spawn-command-builder\"],\"localWrites\":[\"skills/calibre-metadata-apply/state/runs.json\",\"~/.config/calibre-metadata-apply/auth.json\",\"~/.config/calibre-metadata-apply/config.json\"],\"modifiesRemoteData\":[\"calibre:metadata\"]}}\n---\n\n# calibre-metadata-apply\n\nA skill for updating metadata of existing Calibre books.\n\n## Skill selection contract (strict)\n\n- If the user intent is metadata edit/fix/update, this skill is mandatory.\n- If the request mentions ID-based title fix (e.g. `ID1011 タイトル修正`), this skill is mandatory.\n- `calibre-catalog-read` must not be used for those edit intents.\n\nUse this skill when the user asks any of:\n- \"ID指定でタイトル修正\"\n- \"メタデータ編集\"\n- `title/authors/series/series_index/tags/publisher/pubdate/languages` updates\n\nDo NOT route those requests to `calibre-catalog-read`.\n\n## Requirements\n\n- `calibredb` must be available on PATH in the runtime environment\n- `subagent-spawn-command-builder` installed (for spawn payload generation)\n- `pdffonts` is optional/recommended for PDF evidence checks\n- Reachable Calibre Content server URL\n - `http://HOST:PORT/#LIBRARY_ID`\n - If `LIBRARY_ID` is unknown, use `#-` once to list available IDs on the server.\n- `--with-library` can be omitted only when one of these is configured:\n - env: `CALIBRE_WITH_LIBRARY` or `CALIBRE_LIBRARY_URL` or `CALIBRE_CONTENT_SERVER_URL`\n - config: `~/.config/calibre-metadata-apply/config.json` with `with_library`\n - optional library id completion: `CALIBRE_LIBRARY_ID` or config `library_id`\n- Host failover (IP change resilience):\n - Optional env: `CALIBRE_SERVER_HOSTS=host1,host2,...`\n - Script auto-tries candidates, including WSL host-side `nameserver` from `/etc/resolv.conf`.\n- If authentication is enabled, prefer `/home/altair/.openclaw/.env`:\n - `CALIBRE_USERNAME=`\n - `CALIBRE_PASSWORD=`\n- Auth scheme policy for this workflow:\n - Non-SSL deployment assumes **Digest** authentication.\n - Do not pass auth mode arguments such as `--auth-mode` / `--auth-scheme`.\n- Pass `--password-env CALIBRE_PASSWORD` (username auto-loads from env)\n- You can still override explicitly with `--username `.\n- Optional auth cache: `--save-auth` (default file: `~/.config/calibre-metadata-apply/auth.json`)\n\n## Supported fields\n\n### Direct fields (`set_metadata --field`)\n- `title`\n- `title_sort`\n- `authors` (string with `&` or array)\n- `author_sort`\n- `series`\n- `series_index`\n- `tags` (string or array)\n- `publisher`\n- `pubdate` (`YYYY-MM-DD`)\n- `languages`\n- `comments`\n\n### Helper fields\n- `comments_html` (OC marker block upsert)\n- `analysis` (auto-generates analysis HTML for comments)\n- `analysis_tags` (adds tags)\n- `tags_merge` (default `true`)\n- `tags_remove` (remove specific tags after merge)\n\n## Required execution flow\n\n### A. Target confirmation (mandatory)\n1. Run read-only lookup to narrow candidates\n2. Show `id,title,authors,series,series_index`\n3. Get user confirmation for final target IDs\n4. Build JSONL using only confirmed IDs\n\n### B. Proposal synthesis (when metadata is missing)\n1. Collect evidence from file extraction + web sources\n2. Show one merged proposal table with:\n - `candidate`, `source`, `confidence (high|medium|low)`\n - `title_sort_candidate`, `author_sort_candidate`\n3. Get user decision:\n - `approve all`\n - `approve only: `\n - `reject: `\n - `edit: =`\n4. Apply only approved/finalized fields\n5. If confidence is low or sources conflict, keep fields empty\n\n### C. Apply\n1. Run dry-run first (mandatory)\n2. Run `--apply` only after explicit user approval\n3. Re-read and report final values\n\n## Analysis worker policy\n\n- Use `subagent-spawn-command-builder` to generate `sessions_spawn` payload for heavy candidate generation\n - `task` is required.\n - Profile should include model/thinking/timeout/cleanup for this workflow.\n- Use lightweight subagent model for analysis (avoid main heavy model)\n- Keep final decisions + dry-run/apply in main\n\n## Data flow disclosure\n\n- Local execution:\n - Build `calibredb set_metadata` commands from JSONL.\n - Read/write local state files (`state/runs.json`) and optional auth/config files under `~/.config/calibre-metadata-apply/`.\n- Subagent execution (optional for heavy candidate generation):\n - Uses `sessions_spawn` via `subagent-spawn-command-builder`.\n - Text/metadata sent to subagent can reach model endpoints configured by runtime profile.\n- Remote write:\n - `calibredb set_metadata` updates metadata on the target Calibre Content server.\n\nSecurity rules:\n- Do not use `--save-plain-password` unless explicitly instructed by the user.\n- Prefer env-based password (`--password-env CALIBRE_PASSWORD`) over inline `--password`.\n- If user does not want external model/subagent processing, keep flow local and skip subagent orchestration.\n- In agent/chat execution, do not call `calibredb` directly for edit operations.\n - Always execute `node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs`.\n- Never run `calibre-server` from this skill.\n - This workflow always targets an already-running Calibre Content server.\n\n## Connection bootstrap (mandatory)\n\n- Do not ask the user for `--with-library` first.\n- First, execute using saved defaults (env/config) with no explicit `--with-library`.\n - Scripts auto-load `.env` and resolve `CALIBRE_WITH_LIBRARY` / `CALIBRE_CONTENT_SERVER_URL`.\n- Ask user for URL only when command output shows unresolved connection, such as:\n - `missing --with-library`\n - `unable to resolve usable --with-library`\n - repeated connection failures for all candidates\n\n## Long-run turn-split policy (library-wide)\n\nFor library-wide heavy processing, always use turn-split execution.\n\n## Unknown-document recovery flow (M3)\n\nBatch sizing rule:\n- Keep each unknown-document batch small enough to show full row-by-row results in chat (no representative sampling).\n- If unresolved items remain, stop and wait for explicit user instruction to start the next batch.\n\n### User intervention checkpoints (fixed)\n\n1. **Light pass (metadata-only)**\n - Always run this stage by default (no extra user instruction required)\n - Analyze existing metadata only (no file content read)\n - Present a table to user:\n - current file/title\n - recommended title/metadata\n - confidence/evidence summary\n - Stop and wait for user instruction before any deeper stage\n\n2. **On user request: page-1 pass**\n - Read only the first page and refine proposals\n - Report delta from light pass\n\n3. **If still uncertain: deep pass**\n - Read first 5 pages + last 5 pages\n - Add web evidence search\n - Produce finalized proposal with confidence + rationale\n\n4. **Approval gate**\n - Show detailed findings and request explicit approval before apply\n\n### Pending and unsupported handling\n\n- Use `pending-review` tag for unresolved/hold items.\n- If document is unresolved in current flow, do not force metadata guesses.\n - Tag with `pending-review` and keep for follow-up investigation.\n\n### Diff report format (for unknown batch runs)\n\nReturn full results (not samples):\n- execution summary (target/changed/pending/skipped/error)\n- full changed list with `id` + key before/after fields\n- full pending list with `id` + reason\n- full error list with `id` + error summary\n- confidence must be expressed as `high|medium|low`\n\n### Runtime artifact policy\n\n- Keep run-state and temporary artifacts only while a run is active.\n- On successful completion, remove per-run state/artifacts.\n- On failure, keep minimal artifacts only for retry/debug, then clean up after resolution.\n\n### Internal orchestration (recommended)\n\n- Use lightweight subagent for all analysis stages\n- Keep apply decisions in main session\n- Persist run state for each stage in `state/runs.json`\n\n### Turn 1 (start)\n1. Main defines scope\n2. Main generates spawn payload via `subagent-spawn-command-builder` (profile example: `calibre-meta`), then calls `sessions_spawn`\n3. Save `run_id/session_key/task` via `scripts/run_state.mjs upsert`\n4. Immediately tell the user this is a subagent job and state the execution model used for analysis\n5. Reply with \"analysis started\" and keep normal chat responsive\n\n### Turn 2 (completion)\n1. Receive subagent completion notice\n2. Save result JSON\n3. Complete state handling via `scripts/handle_completion.mjs --run-id ... --result-json ...`\n4. Return summarized proposal (apply only when needed)\n\nRun state file:\n- `state/runs.json`\n\n## PDF extraction policy\n\n1. Try `ebook-convert` first\n2. If empty/failed, fallback to `pdftotext`\n3. If both fail, switch to web-evidence-first mode\n\n## Sort reading policy\n\n- Use user-configured `reading_script` for Japanese/non-Latin sort fields\n - `katakana` / `hiragana` / `latin`\n- Ask once on first use, then persist and reuse\n- Default policy is full reading (no truncation)\n- Config path: `~/.config/calibre-metadata-apply/config.json`\n - key: `reading_script`\n\n## Usage\n\nDry-run:\n\n```bash\ncat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --lang ja\n```\n\nDry-run (when default library is preconfigured via env/config):\n\n```bash\ncat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \\\n --password-env CALIBRE_PASSWORD \\\n --lang ja\n```\n\nApply:\n\n```bash\ncat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --apply\n```\n\n## Do not\n\n- Do not run direct `--apply` using ambiguous title matches only\n- Do not include unconfirmed IDs in apply payload\n- Do not auto-fill low-confidence candidates without explicit confirmation\n- Do not start a local server with guessed path like `~/Calibre Library`\n\nFile v1.0.2:README.md\n\n# calibre-metadata-apply\n\n`calibredb` を使って、既存Calibre書籍のメタデータを更新するスキルです。\n\n## このスキルの目的\n\nこのスキルは、Calibreライブラリのメタデータ運用を\n**「安全に・継続的に・監査可能に」回す** ための実務スキルです。\n\n### 1) 何を解決するか\n\n- 手作業で崩れやすいメタデータ整備（title/authors/publisher/pubdate/tags/sort）を定型化\n- 1冊編集とライブラリ横断編集を同じ運用ルールで実施\n- 長時間ジョブでもチャットを止めずに進行（ターン分割）\n\n### 2) 何を自動化するか\n\n- 1冊単位の確定編集（確認→dry-run→apply→検証）\n- ライブラリ横断の推定タグ付与（本文ではなく既存メタデータのみを利用）\n- 高確信候補の自動適用と、低確信候補の保留\n\n### 3) 何をしないか（境界）\n\n- 曖昧な対象に対する即時apply\n- 根拠が弱い候補の無条件上書き\n- 本文解析が必要な重処理をmainターンで同期実行\n\n### 4) 想定ユースケース\n\n- 「ID指定で論文書誌を修正したい」\n- 「マニュアルらしい本に `マニュアル/Manual` を一括付与したい」\n- 「論文らしい本を横断抽出して `論文` タグを付けたい」\n\n### 5) 運用ポリシー（要点）\n\n- 高確信な提案のみ自動適用\n- 低確信・衝突ケースは保留/再処理\n- 保留は `pending-review` タグを付与して管理\n- confidence表現は `high/medium/low` に統一\n- 長時間処理はターン分割（開始ACK→完了報告）\n- 実行中の状態/一時ファイルは完了時に削除（失敗時のみ最小限保持）\n\n## セットアップ\n\n1. このスキルを実行する環境にCalibreをインストールする\n - 必須: `calibredb`\n2. PDF調査用に `pdffonts` を使えるようにする（例: `poppler-utils`）\n3. `subagent-spawn-command-builder` を導入する（spawn payload生成に使用）\n\n```bash\nnpx clawhub@latest install subagent-spawn-command-builder\npnpm dlx clawhub@latest install subagent-spawn-command-builder\n```\n\n4. `calibredb` と `pdffonts` が `PATH` で実行できることを確認する\n5. Calibre Content server に到達できることを確認する\n6. `--with-library` は次の形式で指定する\n - `http://HOST:PORT/#LIBRARY_ID`\n - localhost前提にしない（明示的なHOST:PORTを使う）\n - 省略する場合は以下のどれかを事前設定する\n - env: `CALIBRE_WITH_LIBRARY` / `CALIBRE_LIBRARY_URL` / `CALIBRE_CONTENT_SERVER_URL`\n - config: `~/.config/calibre-metadata-apply/config.json` の `with_library`\n - URLに`#LIBRARY_ID`が無い場合は `CALIBRE_LIBRARY_ID` か config `library_id` で補完可能\n - IP変更対策:\n - `CALIBRE_SERVER_HOSTS=host1,host2,...` を設定すると候補を順に試行\n - WSLでは `/etc/resolv.conf` の `nameserver` も自動候補に追加\n - `LIBRARY_ID` が不明な場合は `#-` で一覧確認できる\n - 例: `calibredb list --with-library \"http://HOST:PORT/#-\" --username ... --password ...`\n7. 認証が有効な場合は次を指定する\n - `--username `\n - `--password-env ` または `--password `\n - 認証方式は非SSL運用前提でDigest固定(自動)とし、`--auth-mode` / `--auth-scheme` は使わない\n8. 認証情報を保存して再利用したい場合は `--save-auth` を使う\n - 既定保存先: `~/.config/calibre-metadata-apply/auth.json`\n - 既定では `username` と `password_env` を保存\n - 平文パスワードも保存する場合のみ `--save-plain-password` を追加\n\n### ユーザーが先に実行すること（例: Ubuntu/WSL）\n\n```bash\nsudo apt update\nsudo apt install -y calibre poppler-utils\n```\n\n## 重要\n\nOpenClawが入っているだけでは不十分です。実行環境側に `calibredb` が必要です。\nチャット実行時は `calibredb` 直接実行ではなく、必ず `node scripts/calibredb_apply.mjs` を使ってください。\nこの運用では既存のCalibre Content serverに接続するため、`calibre-server` を起動する手順は不要です。\n\nWindowsではDefender Controlled Folder Access等の影響で書き込みが失敗する場合があります。\n`WinError 2/5` などのパス/アクセス系エラーが出る場合は、Calibreライブラリフォルダや実行バイナリを許可リストに追加してください。\n\n## 安全モデル\n\n- 入力はJSONL（1行=1更新）\n- `id` 必須\n- デフォルトはdry-run（`--apply` 指定時のみ書き込み）\n\n## ライブラリ横断処理（ターン分割）\n\n長時間処理はターン分割で実行し、チャット継続性を優先します。\n\n- 開始ターン:\n - `subagent-spawn-command-builder` で `sessions_spawn` payloadを生成（例: `profile=calibre-meta`）\n - 生成payloadで軽量subagentに解析を委譲\n - `scripts/run_state.mjs` で実行状態を記録\n- 完了ターン: 完了通知後、`scripts/handle_completion.mjs` で状態を片付けて結果を提示\n- state保存先: `state/runs.json`\n\n### `spawn-profiles.json` に追加する例（`calibre-meta`）\n\n```json\n{\n \"profiles\": {\n \"calibre-meta\": {\n \"model\": \"openrouter/qwen/qwen3-next-80b-a3b-instruct\",\n \"thinking\": \"low\",\n \"runTimeoutSeconds\": 300,\n \"cleanup\": \"keep\"\n }\n }\n}\n```\n\n## 認証キャッシュ（初回保存）\n\n初回だけ認証情報を保存しておくと、以後は `--username` / `--password-env` を省略できます。\n\n```bash\ncat references/changes.example.jsonl | node scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --save-auth\n```\n\n平文パスワードも保存したい場合（非推奨）は次を追加:\n\n```bash\n--save-plain-password\n```\n\n## クイックテスト（dry-run）\n\n```bash\ncat references/changes.example.jsonl | node scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\"\n```\n\n`--with-library` を省略したい場合は、先に `CALIBRE_WITH_LIBRARY` などを設定してください。\n\nFile v1.0.2:_meta.json\n\n{\n \"ownerId\": \"kn747bx1r2jrbbyca61v6k06397zy93t\",\n \"slug\": \"calibre-metadata-apply\",\n \"version\": \"1.0.2\",\n \"publishedAt\": 1774053219300\n}\n\nArchive v1.0.1: 6 files, 12885 bytes\n\nFiles: README.md (5027b), scripts/calibredb_apply.mjs (11197b), scripts/handle_completion.mjs (1989b), scripts/run_state.mjs (3259b), SKILL.md (7936b), _meta.json (141b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: calibre-metadata-apply\ndescription: Apply metadata updates to existing Calibre books via calibredb over a Content server. Use for controlled metadata edits after target IDs are confirmed by a read-only lookup.\nmetadata: {\"openclaw\":{\"requires\":{\"bins\":[\"node\",\"calibredb\"],\"env\":[\"CALIBRE_PASSWORD\"]},\"optionalBins\":[\"pdffonts\"],\"optionalEnv\":[\"CALIBRE_USERNAME\"],\"primaryEnv\":\"CALIBRE_PASSWORD\",\"dependsOnSkills\":[\"subagent-spawn-command-builder\"],\"localWrites\":[\"skills/calibre-metadata-apply/state/runs.json\",\"~/.config/calibre-metadata-apply/auth.json\",\"~/.config/calibre-metadata-apply/config.json\"],\"modifiesRemoteData\":[\"calibre:metadata\"]}}\n---\n\n# calibre-metadata-apply\n\nA skill for updating metadata of existing Calibre books.\n\n## Requirements\n\n- `calibredb` must be available on PATH in the runtime environment\n- `subagent-spawn-command-builder` installed (for spawn payload generation)\n- `pdffonts` is optional/recommended for PDF evidence checks\n- Reachable Calibre Content server URL\n - `http://HOST:PORT/#LIBRARY_ID`\n- If authentication is enabled, prefer `/home/altair/.openclaw/.env`:\n - `CALIBRE_USERNAME=`\n - `CALIBRE_PASSWORD=`\n- Pass `--password-env CALIBRE_PASSWORD` (username auto-loads from env)\n- You can still override explicitly with `--username `.\n- Optional auth cache: `--save-auth` (default file: `~/.config/calibre-metadata-apply/auth.json`)\n\n## Supported fields\n\n### Direct fields (`set_metadata --field`)\n- `title`\n- `title_sort`\n- `authors` (string with `&` or array)\n- `author_sort`\n- `series`\n- `series_index`\n- `tags` (string or array)\n- `publisher`\n- `pubdate` (`YYYY-MM-DD`)\n- `languages`\n- `comments`\n\n### Helper fields\n- `comments_html` (OC marker block upsert)\n- `analysis` (auto-generates analysis HTML for comments)\n- `analysis_tags` (adds tags)\n- `tags_merge` (default `true`)\n- `tags_remove` (remove specific tags after merge)\n\n## Required execution flow\n\n### A. Target confirmation (mandatory)\n1. Run read-only lookup to narrow candidates\n2. Show `id,title,authors,series,series_index`\n3. Get user confirmation for final target IDs\n4. Build JSONL using only confirmed IDs\n\n### B. Proposal synthesis (when metadata is missing)\n1. Collect evidence from file extraction + web sources\n2. Show one merged proposal table with:\n - `candidate`, `source`, `confidence (high|medium|low)`\n - `title_sort_candidate`, `author_sort_candidate`\n3. Get user decision:\n - `approve all`\n - `approve only: `\n - `reject: `\n - `edit: =`\n4. Apply only approved/finalized fields\n5. If confidence is low or sources conflict, keep fields empty\n\n### C. Apply\n1. Run dry-run first (mandatory)\n2. Run `--apply` only after explicit user approval\n3. Re-read and report final values\n\n## Analysis worker policy\n\n- Use `subagent-spawn-command-builder` to generate `sessions_spawn` payload for heavy candidate generation\n - `task` is required.\n - Profile should include model/thinking/timeout/cleanup for this workflow.\n- Use lightweight subagent model for analysis (avoid main heavy model)\n- Keep final decisions + dry-run/apply in main\n\n## Data flow disclosure\n\n- Local execution:\n - Build `calibredb set_metadata` commands from JSONL.\n - Read/write local state files (`state/runs.json`) and optional auth/config files under `~/.config/calibre-metadata-apply/`.\n- Subagent execution (optional for heavy candidate generation):\n - Uses `sessions_spawn` via `subagent-spawn-command-builder`.\n - Text/metadata sent to subagent can reach model endpoints configured by runtime profile.\n- Remote write:\n - `calibredb set_metadata` updates metadata on the target Calibre Content server.\n\nSecurity rules:\n- Do not use `--save-plain-password` unless explicitly instructed by the user.\n- Prefer env-based password (`--password-env CALIBRE_PASSWORD`) over inline `--password`.\n- If user does not want external model/subagent processing, keep flow local and skip subagent orchestration.\n\n## Long-run turn-split policy (library-wide)\n\nFor library-wide heavy processing, always use turn-split execution.\n\n## Unknown-document recovery flow (M3)\n\nBatch sizing rule:\n- Keep each unknown-document batch small enough to show full row-by-row results in chat (no representative sampling).\n- If unresolved items remain, stop and wait for explicit user instruction to start the next batch.\n\n### User intervention checkpoints (fixed)\n\n1. **Light pass (metadata-only)**\n - Always run this stage by default (no extra user instruction required)\n - Analyze existing metadata only (no file content read)\n - Present a table to user:\n - current file/title\n - recommended title/metadata\n - confidence/evidence summary\n - Stop and wait for user instruction before any deeper stage\n\n2. **On user request: page-1 pass**\n - Read only the first page and refine proposals\n - Report delta from light pass\n\n3. **If still uncertain: deep pass**\n - Read first 5 pages + last 5 pages\n - Add web evidence search\n - Produce finalized proposal with confidence + rationale\n\n4. **Approval gate**\n - Show detailed findings and request explicit approval before apply\n\n### Pending and unsupported handling\n\n- Use `pending-review` tag for unresolved/hold items.\n- If document is unresolved in current flow, do not force metadata guesses.\n - Tag with `pending-review` and keep for follow-up investigation.\n\n### Diff report format (for unknown batch runs)\n\nReturn full results (not samples):\n- execution summary (target/changed/pending/skipped/error)\n- full changed list with `id` + key before/after fields\n- full pending list with `id` + reason\n- full error list with `id` + error summary\n- confidence must be expressed as `high|medium|low`\n\n### Runtime artifact policy\n\n- Keep run-state and temporary artifacts only while a run is active.\n- On successful completion, remove per-run state/artifacts.\n- On failure, keep minimal artifacts only for retry/debug, then clean up after resolution.\n\n### Internal orchestration (recommended)\n\n- Use lightweight subagent for all analysis stages\n- Keep apply decisions in main session\n- Persist run state for each stage in `state/runs.json`\n\n### Turn 1 (start)\n1. Main defines scope\n2. Main generates spawn payload via `subagent-spawn-command-builder` (profile example: `calibre-meta`), then calls `sessions_spawn`\n3. Save `run_id/session_key/task` via `scripts/run_state.mjs upsert`\n4. Immediately tell the user this is a subagent job and state the execution model used for analysis\n5. Reply with \"analysis started\" and keep normal chat responsive\n\n### Turn 2 (completion)\n1. Receive subagent completion notice\n2. Save result JSON\n3. Complete state handling via `scripts/handle_completion.mjs --run-id ... --result-json ...`\n4. Return summarized proposal (apply only when needed)\n\nRun state file:\n- `state/runs.json`\n\n## PDF extraction policy\n\n1. Try `ebook-convert` first\n2. If empty/failed, fallback to `pdftotext`\n3. If both fail, switch to web-evidence-first mode\n\n## Sort reading policy\n\n- Use user-configured `reading_script` for Japanese/non-Latin sort fields\n - `katakana` / `hiragana` / `latin`\n- Ask once on first use, then persist and reuse\n- Default policy is full reading (no truncation)\n- Config path: `~/.config/calibre-metadata-apply/config.json`\n - key: `reading_script`\n\n## Usage\n\nDry-run:\n\n```bash\ncat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --lang ja\n```\n\nApply:\n\n```bash\ncat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --apply\n```\n\n## Do not\n\n- Do not run direct `--apply` using ambiguous title matches only\n- Do not include unconfirmed IDs in apply payload\n- Do not auto-fill low-confidence candidates without explicit confirmation\n\nFile v1.0.1:README.md\n\n# calibre-metadata-apply\n\n`calibredb` を使って、既存Calibre書籍のメタデータを更新するスキルです。\n\n## このスキルの目的\n\nこのスキルは、Calibreライブラリのメタデータ運用を\n**「安全に・継続的に・監査可能に」回す** ための実務スキルです。\n\n### 1) 何を解決するか\n\n- 手作業で崩れやすいメタデータ整備（title/authors/publisher/pubdate/tags/sort）を定型化\n- 1冊編集とライブラリ横断編集を同じ運用ルールで実施\n- 長時間ジョブでもチャットを止めずに進行（ターン分割）\n\n### 2) 何を自動化するか\n\n- 1冊単位の確定編集（確認→dry-run→apply→検証）\n- ライブラリ横断の推定タグ付与（本文ではなく既存メタデータのみを利用）\n- 高確信候補の自動適用と、低確信候補の保留\n\n### 3) 何をしないか（境界）\n\n- 曖昧な対象に対する即時apply\n- 根拠が弱い候補の無条件上書き\n- 本文解析が必要な重処理をmainターンで同期実行\n\n### 4) 想定ユースケース\n\n- 「ID指定で論文書誌を修正したい」\n- 「マニュアルらしい本に `マニュアル/Manual` を一括付与したい」\n- 「論文らしい本を横断抽出して `論文` タグを付けたい」\n\n### 5) 運用ポリシー（要点）\n\n- 高確信な提案のみ自動適用\n- 低確信・衝突ケースは保留/再処理\n- 保留は `pending-review` タグを付与して管理\n- confidence表現は `high/medium/low` に統一\n- 長時間処理はターン分割（開始ACK→完了報告）\n- 実行中の状態/一時ファイルは完了時に削除（失敗時のみ最小限保持）\n\n## セットアップ\n\n1. このスキルを実行する環境にCalibreをインストールする\n - 必須: `calibredb`\n2. PDF調査用に `pdffonts` を使えるようにする（例: `poppler-utils`）\n3. `subagent-spawn-command-builder` を導入する（spawn payload生成に使用）\n\n```bash\nnpx clawhub@latest install subagent-spawn-command-builder\npnpm dlx clawhub@latest install subagent-spawn-command-builder\n```\n\n4. `calibredb` と `pdffonts` が `PATH` で実行できることを確認する\n5. Calibre Content server に到達できることを確認する\n6. `--with-library` は次の形式で指定する\n - `http://HOST:PORT/#LIBRARY_ID`\n - localhost前提にしない（明示的なHOST:PORTを使う）\n7. 認証が有効な場合は次を指定する\n - `--username `\n - `--password-env ` または `--password `\n8. 認証情報を保存して再利用したい場合は `--save-auth` を使う\n - 既定保存先: `~/.config/calibre-metadata-apply/auth.json`\n - 既定では `username` と `password_env` を保存\n - 平文パスワードも保存する場合のみ `--save-plain-password` を追加\n\n### ユーザーが先に実行すること（例: Ubuntu/WSL）\n\n```bash\nsudo apt update\nsudo apt install -y calibre poppler-utils\n```\n\n## 重要\n\nOpenClawが入っているだけでは不十分です。実行環境側に `calibredb` が必要です。\n\nWindowsではDefender Controlled Folder Access等の影響で書き込みが失敗する場合があります。\n`WinError 2/5` などのパス/アクセス系エラーが出る場合は、Calibreライブラリフォルダや実行バイナリを許可リストに追加してください。\n\n## 安全モデル\n\n- 入力はJSONL（1行=1更新）\n- `id` 必須\n- デフォルトはdry-run（`--apply` 指定時のみ書き込み）\n\n## ライブラリ横断処理（ターン分割）\n\n長時間処理はターン分割で実行し、チャット継続性を優先します。\n\n- 開始ターン:\n - `subagent-spawn-command-builder` で `sessions_spawn` payloadを生成（例: `profile=calibre-meta`）\n - 生成payloadで軽量subagentに解析を委譲\n - `scripts/run_state.mjs` で実行状態を記録\n- 完了ターン: 完了通知後、`scripts/handle_completion.mjs` で状態を片付けて結果を提示\n- state保存先: `state/runs.json`\n\n### `spawn-profiles.json` に追加する例（`calibre-meta`）\n\n```json\n{\n \"profiles\": {\n \"calibre-meta\": {\n \"model\": \"openrouter/qwen/qwen3-next-80b-a3b-instruct\",\n \"thinking\": \"low\",\n \"runTimeoutSeconds\": 300,\n \"cleanup\": \"keep\"\n }\n }\n}\n```\n\n## 認証キャッシュ（初回保存）\n\n初回だけ認証情報を保存しておくと、以後は `--username` / `--password-env` を省略できます。\n\n```bash\ncat references/changes.example.jsonl | node scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --save-auth\n```\n\n平文パスワードも保存したい場合（非推奨）は次を追加:\n\n```bash\n--save-plain-password\n```\n\n## クイックテスト（dry-run）\n\n```bash\ncat references/changes.example.jsonl | node scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\"\n```\n\nFile v1.0.1:_meta.json\n\n{\n \"ownerId\": \"kn747bx1r2jrbbyca61v6k06397zy93t\",\n \"slug\": \"calibre-metadata-apply\",\n \"version\": \"1.0.1\",\n \"publishedAt\": 1770993524746\n}\n\nArchive v1.0.0: 6 files, 12204 bytes\n\nFiles: README.md (5027b), scripts/calibredb_apply.mjs (10858b), scripts/handle_completion.mjs (1650b), scripts/run_state.mjs (3259b), SKILL.md (6593b), _meta.json (141b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: calibre-metadata-apply\ndescription: Apply metadata updates to existing Calibre books via calibredb over a Content server. Use for controlled metadata edits after target IDs are confirmed by a read-only lookup.\n---\n\n# calibre-metadata-apply\n\nA skill for updating metadata of existing Calibre books.\n\n## Requirements\n\n- `calibredb` must be available on PATH in the runtime environment\n- `subagent-spawn-command-builder` installed (for spawn payload generation)\n- Reachable Calibre Content server URL\n - `http://HOST:PORT/#LIBRARY_ID`\n- If authentication is enabled, prefer `/home/altair/.openclaw/.env`:\n - `CALIBRE_USERNAME=`\n - `CALIBRE_PASSWORD=`\n- Pass `--password-env CALIBRE_PASSWORD` (username auto-loads from env)\n- You can still override explicitly with `--username `.\n- Optional auth cache: `--save-auth` (default file: `~/.config/calibre-metadata-apply/auth.json`)\n\n## Supported fields\n\n### Direct fields (`set_metadata --field`)\n- `title`\n- `title_sort`\n- `authors` (string with `&` or array)\n- `author_sort`\n- `series`\n- `series_index`\n- `tags` (string or array)\n- `publisher`\n- `pubdate` (`YYYY-MM-DD`)\n- `languages`\n- `comments`\n\n### Helper fields\n- `comments_html` (OC marker block upsert)\n- `analysis` (auto-generates analysis HTML for comments)\n- `analysis_tags` (adds tags)\n- `tags_merge` (default `true`)\n- `tags_remove` (remove specific tags after merge)\n\n## Required execution flow\n\n### A. Target confirmation (mandatory)\n1. Run read-only lookup to narrow candidates\n2. Show `id,title,authors,series,series_index`\n3. Get user confirmation for final target IDs\n4. Build JSONL using only confirmed IDs\n\n### B. Proposal synthesis (when metadata is missing)\n1. Collect evidence from file extraction + web sources\n2. Show one merged proposal table with:\n - `candidate`, `source`, `confidence (high|medium|low)`\n - `title_sort_candidate`, `author_sort_candidate`\n3. Get user decision:\n - `approve all`\n - `approve only: `\n - `reject: `\n - `edit: =`\n4. Apply only approved/finalized fields\n5. If confidence is low or sources conflict, keep fields empty\n\n### C. Apply\n1. Run dry-run first (mandatory)\n2. Run `--apply` only after explicit user approval\n3. Re-read and report final values\n\n## Analysis worker policy\n\n- Use `subagent-spawn-command-builder` to generate `sessions_spawn` payload for heavy candidate generation\n - `task` is required.\n - Profile should include model/thinking/timeout/cleanup for this workflow.\n- Use lightweight subagent model for analysis (avoid main heavy model)\n- Keep final decisions + dry-run/apply in main\n\n## Long-run turn-split policy (library-wide)\n\nFor library-wide heavy processing, always use turn-split execution.\n\n## Unknown-document recovery flow (M3)\n\nBatch sizing rule:\n- Keep each unknown-document batch small enough to show full row-by-row results in chat (no representative sampling).\n- If unresolved items remain, stop and wait for explicit user instruction to start the next batch.\n\n### User intervention checkpoints (fixed)\n\n1. **Light pass (metadata-only)**\n - Always run this stage by default (no extra user instruction required)\n - Analyze existing metadata only (no file content read)\n - Present a table to user:\n - current file/title\n - recommended title/metadata\n - confidence/evidence summary\n - Stop and wait for user instruction before any deeper stage\n\n2. **On user request: page-1 pass**\n - Read only the first page and refine proposals\n - Report delta from light pass\n\n3. **If still uncertain: deep pass**\n - Read first 5 pages + last 5 pages\n - Add web evidence search\n - Produce finalized proposal with confidence + rationale\n\n4. **Approval gate**\n - Show detailed findings and request explicit approval before apply\n\n### Pending and unsupported handling\n\n- Use `pending-review` tag for unresolved/hold items.\n- If document is unresolved in current flow, do not force metadata guesses.\n - Tag with `pending-review` and keep for follow-up investigation.\n\n### Diff report format (for unknown batch runs)\n\nReturn full results (not samples):\n- execution summary (target/changed/pending/skipped/error)\n- full changed list with `id` + key before/after fields\n- full pending list with `id` + reason\n- full error list with `id` + error summary\n- confidence must be expressed as `high|medium|low`\n\n### Runtime artifact policy\n\n- Keep run-state and temporary artifacts only while a run is active.\n- On successful completion, remove per-run state/artifacts.\n- On failure, keep minimal artifacts only for retry/debug, then clean up after resolution.\n\n### Internal orchestration (recommended)\n\n- Use lightweight subagent for all analysis stages\n- Keep apply decisions in main session\n- Persist run state for each stage in `state/runs.json`\n\n### Turn 1 (start)\n1. Main defines scope\n2. Main generates spawn payload via `subagent-spawn-command-builder` (profile example: `calibre-meta`), then calls `sessions_spawn`\n3. Save `run_id/session_key/task` via `scripts/run_state.mjs upsert`\n4. Immediately tell the user this is a subagent job and state the execution model used for analysis\n5. Reply with \"analysis started\" and keep normal chat responsive\n\n### Turn 2 (completion)\n1. Receive subagent completion notice\n2. Save result JSON\n3. Complete state handling via `scripts/handle_completion.mjs --run-id ... --result-json ...`\n4. Return summarized proposal (apply only when needed)\n\nRun state file:\n- `state/runs.json`\n\n## PDF extraction policy\n\n1. Try `ebook-convert` first\n2. If empty/failed, fallback to `pdftotext`\n3. If both fail, switch to web-evidence-first mode\n\n## Sort reading policy\n\n- Use user-configured `reading_script` for Japanese/non-Latin sort fields\n - `katakana` / `hiragana` / `latin`\n- Ask once on first use, then persist and reuse\n- Default policy is full reading (no truncation)\n- Config path: `~/.config/calibre-metadata-apply/config.json`\n - key: `reading_script`\n\n## Usage\n\nDry-run:\n\n```bash\ncat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --lang ja\n```\n\nApply:\n\n```bash\ncat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --apply\n```\n\n## Do not\n\n- Do not run direct `--apply` using ambiguous title matches only\n- Do not include unconfirmed IDs in apply payload\n- Do not auto-fill low-confidence candidates without explicit confirmation\n\nFile v1.0.0:README.md\n\n# calibre-metadata-apply\n\n`calibredb` を使って、既存Calibre書籍のメタデータを更新するスキルです。\n\n## このスキルの目的\n\nこのスキルは、Calibreライブラリのメタデータ運用を\n**「安全に・継続的に・監査可能に」回す** ための実務スキルです。\n\n### 1) 何を解決するか\n\n- 手作業で崩れやすいメタデータ整備（title/authors/publisher/pubdate/tags/sort）を定型化\n- 1冊編集とライブラリ横断編集を同じ運用ルールで実施\n- 長時間ジョブでもチャットを止めずに進行（ターン分割）\n\n### 2) 何を自動化するか\n\n- 1冊単位の確定編集（確認→dry-run→apply→検証）\n- ライブラリ横断の推定タグ付与（本文ではなく既存メタデータのみを利用）\n- 高確信候補の自動適用と、低確信候補の保留\n\n### 3) 何をしないか（境界）\n\n- 曖昧な対象に対する即時apply\n- 根拠が弱い候補の無条件上書き\n- 本文解析が必要な重処理をmainターンで同期実行\n\n### 4) 想定ユースケース\n\n- 「ID指定で論文書誌を修正したい」\n- 「マニュアルらしい本に `マニュアル/Manual` を一括付与したい」\n- 「論文らしい本を横断抽出して `論文` タグを付けたい」\n\n### 5) 運用ポリシー（要点）\n\n- 高確信な提案のみ自動適用\n- 低確信・衝突ケースは保留/再処理\n- 保留は `pending-review` タグを付与して管理\n- confidence表現は `high/medium/low` に統一\n- 長時間処理はターン分割（開始ACK→完了報告）\n- 実行中の状態/一時ファイルは完了時に削除（失敗時のみ最小限保持）\n\n## セットアップ\n\n1. このスキルを実行する環境にCalibreをインストールする\n - 必須: `calibredb`\n2. PDF調査用に `pdffonts` を使えるようにする（例: `poppler-utils`）\n3. `subagent-spawn-command-builder` を導入する（spawn payload生成に使用）\n\n```bash\nnpx clawhub@latest install subagent-spawn-command-builder\npnpm dlx clawhub@latest install subagent-spawn-command-builder\n```\n\n4. `calibredb` と `pdffonts` が `PATH` で実行できることを確認する\n5. Calibre Content server に到達できることを確認する\n6. `--with-library` は次の形式で指定する\n - `http://HOST:PORT/#LIBRARY_ID`\n - localhost前提にしない（明示的なHOST:PORTを使う）\n7. 認証が有効な場合は次を指定する\n - `--username `\n - `--password-env ` または `--password `\n8. 認証情報を保存して再利用したい場合は `--save-auth` を使う\n - 既定保存先: `~/.config/calibre-metadata-apply/auth.json`\n - 既定では `username` と `password_env` を保存\n - 平文パスワードも保存する場合のみ `--save-plain-password` を追加\n\n### ユーザーが先に実行すること（例: Ubuntu/WSL）\n\n```bash\nsudo apt update\nsudo apt install -y calibre poppler-utils\n```\n\n## 重要\n\nOpenClawが入っているだけでは不十分です。実行環境側に `calibredb` が必要です。\n\nWindowsではDefender Controlled Folder Access等の影響で書き込みが失敗する場合があります。\n`WinError 2/5` などのパス/アクセス系エラーが出る場合は、Calibreライブラリフォルダや実行バイナリを許可リストに追加してください。\n\n## 安全モデル\n\n- 入力はJSONL（1行=1更新）\n- `id` 必須\n- デフォルトはdry-run（`--apply` 指定時のみ書き込み）\n\n## ライブラリ横断処理（ターン分割）\n\n長時間処理はターン分割で実行し、チャット継続性を優先します。\n\n- 開始ターン:\n - `subagent-spawn-command-builder` で `sessions_spawn` payloadを生成（例: `profile=calibre-meta`）\n - 生成payloadで軽量subagentに解析を委譲\n - `scripts/run_state.mjs` で実行状態を記録\n- 完了ターン: 完了通知後、`scripts/handle_completion.mjs` で状態を片付けて結果を提示\n- state保存先: `state/runs.json`\n\n### `spawn-profiles.json` に追加する例（`calibre-meta`）\n\n```json\n{\n \"profiles\": {\n \"calibre-meta\": {\n \"model\": \"openrouter/qwen/qwen3-next-80b-a3b-instruct\",\n \"thinking\": \"low\",\n \"runTimeoutSeconds\": 300,\n \"cleanup\": \"keep\"\n }\n }\n}\n```\n\n## 認証キャッシュ（初回保存）\n\n初回だけ認証情報を保存しておくと、以後は `--username` / `--password-env` を省略できます。\n\n```bash\ncat references/changes.example.jsonl | node scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --save-auth\n```\n\n平文パスワードも保存したい場合（非推奨）は次を追加:\n\n```bash\n--save-plain-password\n```\n\n## クイックテスト（dry-run）\n\n```bash\ncat references/changes.example.jsonl | node scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\"\n```\n\nFile v1.0.0:_meta.json\n\n{\n \"ownerId\": \"kn747bx1r2jrbbyca61v6k06397zy93t\",\n \"slug\": \"calibre-metadata-apply\",\n \"version\": \"1.0.0\",\n \"publishedAt\": 1770988997625\n}\n\nArchive v0.1.0: 6 files, 12150 bytes\n\nFiles: README.md (5052b), scripts/calibredb_apply.py (12899b), scripts/handle_completion.py (1350b), scripts/run_state.py (3520b), SKILL.md (6331b), _meta.json (141b)\n\nFile v0.1.0:SKILL.md\n\n---\nname: calibre-metadata-apply\ndescription: Apply metadata updates to existing Calibre books via calibredb over a Content server. Use for controlled metadata edits after target IDs are confirmed by a read-only lookup.\n---\n\n# calibre-metadata-apply\n\nA skill for updating metadata of existing Calibre books.\n\n## Requirements\n\n- `calibredb` must be available on PATH in the runtime environment\n- `subagent-spawn-command-builder` installed (for spawn payload generation)\n- Reachable Calibre Content server URL\n - `http://HOST:PORT/#LIBRARY_ID`\n- If authentication is enabled, pass both `--username` and `--password-env`\n- Optional auth cache: `--save-auth` (default file: `~/.config/calibre-metadata-apply/auth.json`)\n\n## Supported fields\n\n### Direct fields (`set_metadata --field`)\n- `title`\n- `title_sort`\n- `authors` (string with `&` or array)\n- `author_sort`\n- `series`\n- `series_index`\n- `tags` (string or array)\n- `publisher`\n- `pubdate` (`YYYY-MM-DD`)\n- `languages`\n- `comments`\n\n### Helper fields\n- `comments_html` (OC marker block upsert)\n- `analysis` (auto-generates analysis HTML for comments)\n- `analysis_tags` (adds tags)\n- `tags_merge` (default `true`)\n- `tags_remove` (remove specific tags after merge)\n\n## Required execution flow\n\n### A. Target confirmation (mandatory)\n1. Run read-only lookup to narrow candidates\n2. Show `id,title,authors,series,series_index`\n3. Get user confirmation for final target IDs\n4. Build JSONL using only confirmed IDs\n\n### B. Proposal synthesis (when metadata is missing)\n1. Collect evidence from file extraction + web sources\n2. Show one merged proposal table with:\n - `candidate`, `source`, `confidence (high|medium|low)`\n - `title_sort_candidate`, `author_sort_candidate`\n3. Get user decision:\n - `approve all`\n - `approve only: `\n - `reject: `\n - `edit: =`\n4. Apply only approved/finalized fields\n5. If confidence is low or sources conflict, keep fields empty\n\n### C. Apply\n1. Run dry-run first (mandatory)\n2. Run `--apply` only after explicit user approval\n3. Re-read and report final values\n\n## Analysis worker policy\n\n- Use `subagent-spawn-command-builder` to generate `sessions_spawn` payload for heavy candidate generation\n - `task` is required.\n - Profile should include model/thinking/timeout/cleanup for this workflow.\n- Use lightweight subagent model for analysis (avoid main heavy model)\n- Keep final decisions + dry-run/apply in main\n\n## Long-run turn-split policy (library-wide)\n\nFor library-wide heavy processing, always use turn-split execution.\n\n## Unknown-document recovery flow (M3)\n\nBatch sizing rule:\n- Keep each unknown-document batch small enough to show full row-by-row results in chat (no representative sampling).\n- If unresolved items remain, stop and wait for explicit user instruction to start the next batch.\n\n### User intervention checkpoints (fixed)\n\n1. **Light pass (metadata-only)**\n - Always run this stage by default (no extra user instruction required)\n - Analyze existing metadata only (no file content read)\n - Present a table to user:\n - current file/title\n - recommended title/metadata\n - confidence/evidence summary\n - Stop and wait for user instruction before any deeper stage\n\n2. **On user request: page-1 pass**\n - Read only the first page and refine proposals\n - Report delta from light pass\n\n3. **If still uncertain: deep pass**\n - Read first 5 pages + last 5 pages\n - Add web evidence search\n - Produce finalized proposal with confidence + rationale\n\n4. **Approval gate**\n - Show detailed findings and request explicit approval before apply\n\n### Pending and unsupported handling\n\n- Use `pending-review` tag for unresolved/hold items.\n- If document is unresolved in current flow, do not force metadata guesses.\n - Tag with `pending-review` and keep for follow-up investigation.\n\n### Diff report format (for unknown batch runs)\n\nReturn full results (not samples):\n- execution summary (target/changed/pending/skipped/error)\n- full changed list with `id` + key before/after fields\n- full pending list with `id` + reason\n- full error list with `id` + error summary\n- confidence must be expressed as `high|medium|low`\n\n### Runtime artifact policy\n\n- Keep run-state and temporary artifacts only while a run is active.\n- On successful completion, remove per-run state/artifacts.\n- On failure, keep minimal artifacts only for retry/debug, then clean up after resolution.\n\n### Internal orchestration (recommended)\n\n- Use lightweight subagent for all analysis stages\n- Keep apply decisions in main session\n- Persist run state for each stage in `state/runs.json`\n\n### Turn 1 (start)\n1. Main defines scope\n2. Main generates spawn payload via `subagent-spawn-command-builder` (profile example: `calibre-meta`), then calls `sessions_spawn`\n3. Save `run_id/session_key/task` via `scripts/run_state.py upsert`\n4. Immediately tell the user this is a subagent job and state the execution model used for analysis\n5. Reply with \"analysis started\" and keep normal chat responsive\n\n### Turn 2 (completion)\n1. Receive subagent completion notice\n2. Save result JSON\n3. Complete state handling via `scripts/handle_completion.py --run-id ... --result-json ...`\n4. Return summarized proposal (apply only when needed)\n\nRun state file:\n- `state/runs.json`\n\n## PDF extraction policy\n\n1. Try `ebook-convert` first\n2. If empty/failed, fallback to `pdftotext`\n3. If both fail, switch to web-evidence-first mode\n\n## Sort reading policy\n\n- Use user-configured `reading_script` for Japanese/non-Latin sort fields\n - `katakana` / `hiragana` / `latin`\n- Ask once on first use, then persist and reuse\n- Default policy is full reading (no truncation)\n- Config path: `~/.config/calibre-metadata-apply/config.json`\n - key: `reading_script`\n\n## Usage\n\nDry-run:\n\n```bash\ncat changes.jsonl | python3 skills/calibre-metadata-apply/scripts/calibredb_apply.py \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --lang ja\n```\n\nApply:\n\n```bash\ncat changes.jsonl | python3 skills/calibre-metadata-apply/scripts/calibredb_apply.py \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --apply\n```\n\n## Do not\n\n- Do not run direct `--apply` using ambiguous title matches only\n- Do not include unconfirmed IDs in apply payload\n- Do not auto-fill low-confidence candidates without explicit confirmation\n\nFile v0.1.0:README.md\n\n# calibre-metadata-apply\n\n`calibredb` を使って、既存Calibre書籍のメタデータを更新するスキルです。\n\n## このスキルの目的\n\nこのスキルは、Calibreライブラリのメタデータ運用を\n**「安全に・継続的に・監査可能に」回す** ための実務スキルです。\n\n### 1) 何を解決するか\n\n- 手作業で崩れやすいメタデータ整備（title/authors/publisher/pubdate/tags/sort）を定型化\n- 1冊編集とライブラリ横断編集を同じ運用ルールで実施\n- 長時間ジョブでもチャットを止めずに進行（ターン分割）\n\n### 2) 何を自動化するか\n\n- 1冊単位の確定編集（確認→dry-run→apply→検証）\n- ライブラリ横断の推定タグ付与（本文ではなく既存メタデータのみを利用）\n- 高確信候補の自動適用と、低確信候補の保留\n\n### 3) 何をしないか（境界）\n\n- 曖昧な対象に対する即時apply\n- 根拠が弱い候補の無条件上書き\n- 本文解析が必要な重処理をmainターンで同期実行\n\n### 4) 想定ユースケース\n\n- 「ID指定で論文書誌を修正したい」\n- 「マニュアルらしい本に `マニュアル/Manual` を一括付与したい」\n- 「論文らしい本を横断抽出して `論文` タグを付けたい」\n\n### 5) 運用ポリシー（要点）\n\n- 高確信な提案のみ自動適用\n- 低確信・衝突ケースは保留/再処理\n- 保留は `pending-review` タグを付与して管理\n- confidence表現は `high/medium/low` に統一\n- 長時間処理はターン分割（開始ACK→完了報告）\n- 実行中の状態/一時ファイルは完了時に削除（失敗時のみ最小限保持）\n\n## セットアップ\n\n1. このスキルを実行する環境にCalibreをインストールする\n - 必須: `calibredb`\n2. PDF調査用に `pdffonts` を使えるようにする（例: `poppler-utils`）\n3. `subagent-spawn-command-builder` を導入する（spawn payload生成に使用）\n\n```bash\nnpx clawhub@latest install subagent-spawn-command-builder\npnpm dlx clawhub@latest install subagent-spawn-command-builder\n```\n\n4. `calibredb` と `pdffonts` が `PATH` で実行できることを確認する\n5. Calibre Content server に到達できることを確認する\n6. `--with-library` は次の形式で指定する\n - `http://HOST:PORT/#LIBRARY_ID`\n - localhost前提にしない（明示的なHOST:PORTを使う）\n7. 認証が有効な場合は次を指定する\n - `--username `\n - `--password-env ` または `--password `\n8. 認証情報を保存して再利用したい場合は `--save-auth` を使う\n - 既定保存先: `~/.config/calibre-metadata-apply/auth.json`\n - 既定では `username` と `password_env` を保存\n - 平文パスワードも保存する場合のみ `--save-plain-password` を追加\n\n### ユーザーが先に実行すること（例: Ubuntu/WSL）\n\n```bash\nsudo apt update\nsudo apt install -y calibre poppler-utils\n```\n\n## 重要\n\nOpenClawが入っているだけでは不十分です。実行環境側に `calibredb` が必要です。\n\nWindowsではDefender Controlled Folder Access等の影響で書き込みが失敗する場合があります。\n`WinError 2/5` などのパス/アクセス系エラーが出る場合は、Calibreライブラリフォルダや実行バイナリを許可リストに追加してください。\n\n## 安全モデル\n\n- 入力はJSONL（1行=1更新）\n- `id` 必須\n- デフォルトはdry-run（`--apply` 指定時のみ書き込み）\n\n## ライブラリ横断処理（ターン分割）\n\n長時間処理はターン分割で実行し、チャット継続性を優先します。\n\n- 開始ターン:\n - `subagent-spawn-command-builder` で `sessions_spawn` payloadを生成（例: `profile=calibre-meta`）\n - 生成payloadで軽量subagentに解析を委譲\n - `scripts/run_state.py` で実行状態を記録\n- 完了ターン: 完了通知後、`scripts/handle_completion.py` で状態を片付けて結果を提示\n- state保存先: `state/runs.json`\n\n### `spawn-profiles.json` に追加する例（`calibre-meta`）\n\n```json\n{\n \"profiles\": {\n \"calibre-meta\": {\n \"model\": \"openrouter/qwen/qwen3-next-80b-a3b-instruct\",\n \"thinking\": \"low\",\n \"runTimeoutSeconds\": 300,\n \"cleanup\": \"keep\"\n }\n }\n}\n```\n\n## 認証キャッシュ（初回保存）\n\n初回だけ認証情報を保存しておくと、以後は `--username` / `--password-env` を省略できます。\n\n```bash\ncat references/changes.example.jsonl | python3 scripts/calibredb_apply.py \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --username \"your_user\" --password-env CALIBRE_PASSWORD \\\n --save-auth\n```\n\n平文パスワードも保存したい場合（非推奨）は次を追加:\n\n```bash\n--save-plain-password\n```\n\n## クイックテスト（dry-run）\n\n```bash\ncat references/changes.example.jsonl | python3 scripts/calibredb_apply.py \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\"\n```\n\nFile v0.1.0:_meta.json\n\n{\n \"ownerId\": \"kn747bx1r2jrbbyca61v6k06397zy93t\",\n \"slug\": \"calibre-metadata-apply\",\n \"version\": \"0.1.0\",\n \"publishedAt\": 1770905228557\n}","readmeExcerpt":"Skill: calibre-metadata-apply Owner: nextaltair Summary: Edit Calibre metadata through verified dry-run and apply gates. Tags: latest:1.0.6 Version history: v1.0.6 | 2026-07-30T03:04:09.007Z | user Update local configuration references from retired TOOLS.md to the AGENTS.md Tools section. v1.0.5 | 2026-07-28T07:48:01.710Z | user OpenClaw sessions_spawn direct delegation; remove shared payload-builder dependency. v1.0","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"sudo apt update\nsudo apt install -y calibre poppler-utils"},{"language":"bash","snippet":"cat references/changes.example.jsonl | node scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --save-auth"},{"language":"bash","snippet":"--save-plain-password"},{"language":"bash","snippet":"cat references/changes.example.jsonl | node scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\""},{"language":"bash","snippet":"sudo apt update\nsudo apt install -y calibre poppler-utils"},{"language":"bash","snippet":"cat references/changes.example.jsonl | node scripts/calibredb_apply.mjs \\\n --with-library \"http://127.0.0.1:8080/#MyLibrary\" \\\n --password-env CALIBRE_PASSWORD \\\n --save-auth"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: \"calibre-metadata-apply\"\ndescription: \"Edit Calibre metadata through verified dry-run and apply gates.\"\nmetadata: {\"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\"]}}\n---\n\n# calibre-metadata-apply\n\nUse for Calibre metadata writes. This skill can change remote Calibre metadata.\n\n## Routing\n\nUse when user explicitly asks to edit/fix/update/change:\n- title, title_sort\n- authors, author_sort\n- series, series_index\n- tags, publisher, pubdate, languages\n- comments, analysis, analysis_tags\n\nDo not use for read-only requests such as `ID1021 を確認して`, 詳細, show/view/check. Route those to `calibre-catalog-read`.\n\nID + edit verb means this skill. ID without edit verb means read-only.\n\n## Supported Fields\n\nCore fields:\n- `title`, `title_sort`\n- `authors` as string with `&` or array, `author_sort`\n- `series`, `series_index`\n- `tags` as string or array, `publisher`, `pubdate` as `YYYY-MM-DD`, `languages`\n- `comments`\n\nExtended fields:\n- `comments_html`: OC marker block upsert.\n- `analysis`: auto-generates analysis HTML for comments.\n- `analysis_tags`: adds tags.\n- `tags_merge`: default true.\n- `tags_remove`: remove specific tags after merge.\n\n## Safety Contract\n\nRequired flow:\n1. Run read-only lookup to narrow candidates.\n2. Show `id,title,authors,series,series_index`.\n3. Get user confirmation for target IDs.\n4. Build JSONL only for confirmed IDs.\n5. Dry-run first.\n6. Apply only after explicit user approval.\n7. Re-read and report final values.\n\nNever:\n- Apply ambiguous title matches.\n- Include unconfirmed IDs.\n- Auto-fill low-confidence candidates.\n- Start `calibre-server`.\n- Pass Calibre password inline.\n- Use direct `calibredb` for chat/agent edit operations; use wrapper scripts.\n\n## Local Facts\n\nRead the workspace `AGENTS.md` `## Tools` section for Content server URL, library id, auth, and reading script.\n\nConnection bootstrap:\n- Do not ask the user for `--with-library` first.\n- First use saved defaults with no explicit `--with-library`.\n- Scripts auto-load `.env`.\n- Non-SSL auth is Digest; do not pass auth-mode/auth-scheme flags.\n- Ask for URL only after command output shows unresolved connection.\n- Prefer env-based password with `--password-env CALIBRE_PASSWORD`; username auto-loads from env, or override with `--username`.\n\nRequirements: `calibredb` and `node`; `pdffonts` optional/recommended for PDF evidence checks.\n\n## Commands\n\nDry-run:\n cat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs --password-env CALIBRE_PASSWORD --lang ja\n\nApply:\n cat changes.jsonl | node skills/calibre-metadata-apply/scripts/calibredb_apply.mjs --password-env CALIBRE_PASSWORD --lang ja --apply\n\nRun state:\n node skills/calibre-metadata-apply/scripts/run_state.mjs upsert --run-id --session-key `\n - `--password-env ` または `--password `\n - 認証方式は非SSL運用前提でDigest固定(自動)とし、`--auth-mode` / `--auth-scheme` は使わない\n7. 認証情報を保存して再利用したい場合は `--save-auth` を使う\n - 既定保存先: `~/.config/calibre-metadata-apply/auth.json`\n - 既定では `username` と `password_env` を保存\n - 平文パスワードも保存する場合のみ `--save-plain-password` を追加\n\n### ユーザーが先に実行すること（例: Ubuntu/WSL）\n\n```bash\nsudo apt update\nsudo apt install -y calibre poppler-utils\n```\n\n## 重要\n\nOpenClawが入っているだけでは不十分です。実行環境側に `calibredb` が必要です。\nチャット実行時は `calibredb` 直接実行ではなく、必ず `node scripts/calibredb_apply.mjs` を使ってください。\nこの運用では既存のCalibre Content serverに接続するため、`calibre-server` を起動する手順は不要です。\n\nWindowsではDefender Controlled Folder Access等の影響で書き込みが失敗する場合があります。\n`WinError 2/5` などのパス/アクセス系エラーが出る場合は、Calibreライブラリフォルダや実行バイナリを許可リストに追加してください。\n\n## 安全モデル\n\n- 入力はJSONL（1行=1更新）\n- `id` 必須\n- デフォルトはdry-run（`--apply` 指定時のみ書き込み）\n\n## ライブラリ横断処理（ターン分割）\n\n長時間処理はターン分割で実行し、チャット継続性を優先します。\n\n- 開始ターン:\n - scopeと出力契約を含む自己完結したtaskを作る\n - OpenClaw `sessions_spawn`を直接呼んで解析を委譲\n - `scripts/run_state.mjs` で実行状態を記録\n- 完了ターン: 完了通知後、`scripts/handle_completion.mjs` で状態を片付けて結果を提示\n- state保存先: `state/runs.json`\n\n### Subagent runtime\n\nmodel・thinkingのローカル既定値は設定済みの`calibre-reader` agent profileで管理します。\n\n- OpenClaw `sessions_spawn`を直接呼ぶ。\n- toolが公開する現在のschemaに従い、別の共通payloadを生成しない。\n- mainだけが候補の採否、dry-run、apply、ユーザー応答を担当する。\n\n## 認"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn747bx1r2jrbbyca61v6k06397zy93t\",\n \"slug\": \"calibre-metadata-apply\",\n \"version\": \"1.0.6\",\n \"publishedAt\": 1785380649007\n}"},{"path":"skill-card.md","content":"## Description:\n\nEdit Calibre metadata through verified dry-run and apply gates.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[nextaltair](https://clawhub.ai/user/nextaltair)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and operators use this skill to safely update existing Calibre book metadata, from single-book fixes to library-wide tag operations, using confirmation, dry-run, apply, and verification gates.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can modify remote Calibre metadata and incorrect targets or values could overwrite useful library records.\n\nMitigation: Use the documented candidate narrowing, ID confirmation, dry-run, explicit approval, and re-read steps before and after any apply operation.\n\nRisk: Credential handling and automatic Calibre host probing require trust in the workspace and endpoint configuration.\n\nMitigation: Install only in trusted workspaces, prefer explicit Calibre endpoint settings, pass passwords through environment variables, and use a limited Calibre account where possible.\n\nRisk: Untrusted analysis JSON or raw comments_html could persist unsafe or misleading HTML in Calibre comments.\n\nMitigation: Do not feed untrusted analysis JSON or raw comments_html into apply mode; review generated comments in dry-run output before approving writes.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/nextaltair/skills/calibre-metadata-apply)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Markdown, Shell commands, Configuration, JSON]\n\n**Output Format:** [Markdown guidance with shell commands and JSONL/JSON apply reports]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Uses dry-run output before apply mode and reports final metadata changes after verification.]\n\n## Skill Version(s):\n\n1.0.6 (source: server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1745,"uniquenessScore":42,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T16:29:20.216Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T16:29:20.216Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T21:36:56.796Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}