eBook Manage Skill Bootstrap

Skill Package

下載後的 skill 應該是一個本機資料夾。核心不靠後端服務，而是由 agent 調用 Kobo CLI 和 EPUB reader script。

~/.claude/skills/ebook-manage/
  SKILL.md
  scripts/
    epub_reader.py
  references/
    kobodl-reference.md
    reading-companion-guide.md
    reading-companion-style.md

`SKILL.md`

定義觸發詞、主要工作流、Kobo / EPUB / Book Companion 的入口。

`epub_reader.py`

deterministic parser：輸出 metadata、TOC、chapter content JSON。

`references/`

CLI reference、讀書助手 workflow、章節解讀風格與品質標準。

Agent Contract

當使用者把這份文件丟給 agent，agent 應該照這個順序完成建置，不要只把指令貼給使用者。

Ask for preferences

確認 books directory、Kobo login 方式、進度記錄偏好。

Install dependencies

安裝 `pipx`、`kobodl`、EPUB 解析用 Python packages。

Authenticate Kobo

帶使用者跑 browser OAuth，確認 `kobodl user list` 有帳號。

Verify EPUB flow

匯出 library、下載或指定一本 EPUB、跑 `info` / `toc` / `chapter`。

Co-design Book Companion

討論解讀深度、是否連到個人/公司 context、圖表政策與語言。

Read first chapter

用抽出的章節全文產出第一篇 interpretation，然後保存進度。

Tool Setup

預設 workspace root 是 `$HOME/clawd`，書籍放在 `$HOME/Books/kobo`。這些都可以客製化。

mkdir -p "$HOME/Books/kobo"
mkdir -p "$HOME/clawd/state/reading-companion"

brew install pipx jq
pipx install kobodl
python3 -m pip install ebooklib beautifulsoup4 lxml --break-system-packages

kobodl --help >/dev/null
python3 - <<'PY'
import ebooklib
import bs4
import lxml
print("epub deps ok")
PY

Shebang note: `epub_reader.py` 可能帶有原作者本機路徑。新機器上請明確用 `python3 path/to/epub_reader.py` 執行。

Kobo Auth

`kobodl` 負責 Kobo 連線與授權。這裡沒有 raw API key 要貼到 skill 裡；授權狀態由 `kobodl` 管理。

kobodl user add
kobodl user list
kobodl book list
kobodl book list --read
kobodl book list --export-library /tmp/kobo-library.json

`kobodl user add` 會開 browser OAuth。
Email-login Kobo account 可用；只有 Google/Facebook SSO 時，需要先讓使用者補 email login method。
`--read` 可包含 finished / archived books。

Library Operations

Agent 應該解析 `/tmp/kobo-library.json`，而不是只把原始 JSON 丟給使用者。

JSON field	Meaning	Use
`BookEntitlement.Created`	Purchase date	Sort recent purchases.
`BookEntitlement.RevisionId`	Download id	Pass into `kobodl book get`.
`ReadingState.StatusInfo.Status`	Reading state	Filter reading / finished books.
`ReadingState.CurrentBookmark.ProgressPercent`	Progress	Show current progress.
`BookMetadata.Title` / `ContributorRoles`	Title and author	Display and search.

kobodl book list --export-library /tmp/kobo-library.json
kobodl book get "$REVISION_ID" --output-dir "$HOME/Books/kobo"
ls -lh "$HOME/Books/kobo"/*.epub

EPUB Reader

`epub_reader.py` 是 interpret 前的 source of truth。先 show TOC，再抽 chapter text。

EPUB="/path/to/book.epub"
python3 "$HOME/.claude/skills/ebook-manage/scripts/epub_reader.py" info "$EPUB"
python3 "$HOME/.claude/skills/ebook-manage/scripts/epub_reader.py" toc "$EPUB"
python3 "$HOME/.claude/skills/ebook-manage/scripts/epub_reader.py" chapter "$EPUB" "$CHAPTER_INDEX"

Interpretation guardrail: 不要從章節標題直接解讀。一定要先抽出該章的 `content`。

Book Companion Design

第一次開始讀書前，agent 要先做一輪小型 brainstorming。這是這套系統最該客製化的地方。

Ask these first

解讀要 concise、standard、還是 deep？
要不要連到你的個人筆記、公司專案或研究資料？
章節有框架時，要不要自動畫 diagram？
進度要存在 agent memory、本機 JSON，還是只記這次 session？

Default recommendation

Deep，但依章節密度調整長度。
Context lens 開啟，但只在真的相關時寫出來。
有明確框架或推理鏈才畫圖。
沒有 memory tool 時用 local JSON。

Interpretation Contract

先說本章處理什麼問題。
還原作者的 reasoning chain。
保留重要比喻、案例和知識點。
依原文順序展開，不任意重排。
最後給觀點式 takeaway 與導航 footer。

Progress Tracking

如果 agent 有 memory tool，就用文字記憶；沒有就建立 local JSON。

Reading companion: 《{book_title}》 by {author} — finished chapter {index} "{chapter_title}". EPUB path: {epub_path}.

{
  "book_title": "Escaping the Build Trap",
  "author": "Melissa Perri",
  "epub_path": "/Users/alex/Books/kobo/Melissa Perri - Escaping.epub",
  "last_chapter_index": 3,
  "last_chapter_title": "The Value Exchange System",
  "updated_at": "2026-05-07T10:00:00+08:00"
}

Customization Surface

這些東西不應該寫死在 skill 裡，agent 應該跟使用者確認。

Area	Default	Can customize to
Book directory	`$HOME/Books/kobo`	Any local folder.
Skill location	`$HOME/.claude/skills/ebook-manage`	Agent-specific skill folder.
Progress backend	Memory or local JSON	Memory, JSON, Obsidian note, SQLite.
Interpretation depth	Deep	Concise, standard, deep.
Context lens	Optional	Obsidian, QMD, company KB, project docs.
Diagram policy	Useful frameworks only	Always ask, never, auto.
Output language	User language	繁中、English、bilingual.

Brainstorming Prompts

這些 prompt 可以直接拿來讓 agent 和使用者一起設計閱讀流程。

Reading mode

你希望 reading companion 比較像快速摘要、深度解讀專欄、讀書教練，還是公司策略 lens？

Context access

解讀時要不要連到你的個人筆記、公司專案或研究資料？哪些資料夾或工具是安全可讀的？

Book operations

你通常怎麼找書：最近購買、正在閱讀、語言/作者/主題搜尋，還是直接貼 EPUB path？

Troubleshooting

Symptom	Likely cause	Fix
Kobo login fails	Account uses SSO	Use an email-login Kobo account.
Book missing	Default list hides read or archived items	Run `kobodl book list --read`.
Reader import error	Python lacks `ebooklib` or `bs4`	Install deps or use kobodl pipx venv Python.
TOC looks sparse	EPUB has section headers	Pick child entries with real `chars` counts.
Interpretation feels generic	No style/context questions were asked	Re-run the Book Companion design prompts.

Validation Run

這組通過後，整套 Kobo + EPUB reader + Book Companion 基礎環境就準備好了。

kobodl user list
kobodl book list --export-library /tmp/kobo-library.json

EPUB="/path/to/book.epub"
python3 "$HOME/.claude/skills/ebook-manage/scripts/epub_reader.py" info "$EPUB"
python3 "$HOME/.claude/skills/ebook-manage/scripts/epub_reader.py" toc "$EPUB"
python3 "$HOME/.claude/skills/ebook-manage/scripts/epub_reader.py" chapter "$EPUB" 0

Build a local Kobo reading companion from zero.

Skill Package

Agent Contract

Tool Setup

Kobo Auth

Library Operations

EPUB Reader

Book Companion Design

Ask these first

Default recommendation

Interpretation Contract

Progress Tracking

Customization Surface

Brainstorming Prompts

Troubleshooting

Validation Run