前言

上一篇研究了一個很大的 Agent 教材 repository。讀完一本技術書後，另一個問題隨即出現：幾個月後遇到實際工作，我們還記得書裡有哪些 framework、判斷條件與反例嗎？

virgiliojr94/book-to-skill 想把書從一次性閱讀材料，轉成 Claude Code、GitHub Copilot CLI、Amp 等工具能反覆載入的 Agent Skill。使用者日後問 replication、chapter 5 或某個設計問題時，Agent 只讀核心索引和相關章節，不必每一次把整本 PDF 塞進 context。

這個構想很吸引人，但研究原始碼後，最重要的發現是：它不是一個 Python 程式從頭到尾自動產生可靠 skill。Python 只負責 deterministic extraction；真正的章節理解、框架命名、壓縮與寫檔，是 host agent 依照 SKILL.md 執行。這條責任邊界決定了它的價值，也決定了主要風險。

book-to-skill 是什麼？

它是一個 Agent Skill 產生器，由兩個部分組成：

  1. Python extractor：把 PDF、EPUB、DOCX、Markdown、HTML、RTF、MOBI 等來源整理成 full_text.txt 與 metadata.json。
  2. Spec-driven generator：支援 Agent Skills 的 host agent 讀取 repository 裡的 SKILL.md，再生成一套新的書籍 skill。

輸出通常包含：

檔案 用途
SKILL.md 核心 mental models、chapter index 與 topic index
chapters/*.md 按需讀取的每章整理
glossary.md 關鍵名詞與章節參照
patterns.md Techniques、algorithms 與 design patterns
cheatsheet.md Decision rules、trade-offs 與快速查表

官方 Architecture 把兩半寫得很清楚。若只安裝 Python console command，得到的是文字抽取器，不會自動註冊 /book-to-skill，也不會自行完成 knowledge compilation。

用一個實際案例理解它的價值

假設工程師常回頭查一本分散式系統書，工作問題不是「第 172 頁有沒有 replication 這個詞」，而是：

  • 這個系統該選 leader-based 還是 leaderless replication？
  • 哪些 failure mode 會讓 read-after-write consistency 失效？
  • 作者在哪些條件下建議使用 quorum？
  • 這個方案的 anti-pattern 和判斷門檻是什麼？

直接全文搜尋能找段落，RAG 能找相似 chunks；book-to-skill 則想在轉換階段先抽出作者命名的 frameworks、decision rules、trade-offs 和反例，日後讓 Agent 直接拿這些結構協助工作。

它適合少量、會反覆使用、重視方法與決策的文件，例如技術書、內部 runbook、ADR、品牌規範或一組相關研究。若只問一次問題、需要逐句引用與頁碼證據，或要跨幾十本書廣泛搜尋，先建立 skill 反而不一定合理。

真實資料流：先取文字，再由 Agent 編譯知識

第一階段：解析來源

輸入可以是單一檔案、多個 path、directory 或 glob。程式會展開、排序、去重，再按格式選 parser：input resolution

  • Technical PDF 使用 Docling，保留 Markdown table 與 code block，但目前關閉 OCR。
  • Text-heavy PDF 依序嘗試 pdftotext、pypdf、pdfminer.six。
  • EPUB 優先用 ebooklib，失敗時退回 stdlib ZIP parser。
  • DOCX、HTML、RTF 也有 optional library 與較簡單的 fallback。
  • MOBI／AZW／AZW3 需要外部 Calibre ebook-convert。

每份文字會先移除指定的 zero-width codepoints 與 Unicode tag block，再計算 token、章節和 ToC。成功來源用 SOURCE: banner 合併；單一來源失敗會警告並跳過，全部失敗才停止。batch runner

中間產物是：

book_skill_work/
├── full_text.txt
└── metadata.json

metadata.json 保存 parser、size、page、token、chapter count 與來源統計；full_text.txt 則包含抽取後的正文和來源界線。

第二階段：Host Agent 生成 skill

Agent 依 SKILL.md 執行以下流程：

  1. 確認輸入、輸出 host，以及 technical 或 text-heavy 類型。
  2. 執行 extractor，先回報 token 與成本估算，等待確認。
  3. 分析 title、author、ToC、chapter structure 與 themes。
  4. 根據用途選 reference 或 study depth。
  5. 生成每章 core idea、frameworks、concepts、anti-patterns；technical／study 模式另保留 code、table 或 worked example。
  6. 生成 glossary、patterns 與 decision-oriented cheatsheet。
  7. 建立小於約 4,000 tokens 的 master SKILL.md 和 topic index。
  8. 對全部輸出執行 advisory security scanner；非零時必須人工 review。

超過約 50K tokens 時，規格要求使用 bounded search 和 slices 找 chapter offsets，不要每生成一章就重讀整本書。large-book access rules 這個 progressive disclosure 是專案最有價值的設計之一。

同時也要看清楚：extractor 能測試的是文字取出、清理與 metadata，無法保證模型命名的 framework、重建的 worked example 和 chapter mapping 都忠於原書。這些仍是生成式工作。

安裝與最小使用範例

查核當下最可靠的方式，是把完整 repository clone 到 agent 的 skills folder，並固定 commit：

git clone https://github.com/virgiliojr94/book-to-skill.git \
  ~/.claude/skills/book-to-skill
git -C ~/.claude/skills/book-to-skill checkout \
  b74286d1277ff1ae048e7b7392985bf54aa2987a

python3 ~/.claude/skills/book-to-skill/scripts/extract.py --check

然後在支援 slash command 的 Agent session 內執行：

/book-to-skill ~/books/example.pdf example-book

只想檢查 deterministic extractor，可執行：

export BOOK_SKILL_WORKDIR=/tmp/book-to-skill-example
python3 ~/.claude/skills/book-to-skill/scripts/extract.py \
  ~/books/example.md \
  --mode text \
  --install-missing no

完成後檢查 $BOOK_SKILL_WORKDIR/full_text.txt 與 metadata.json。BOOK_SKILL_WORKDIR 是正式支援的 override。output config

官方 README 和 manifest 也寫了 pip install book-to-skill，但 2026 年 8 月 3 日直接查 PyPI endpoint 得到 HTTP 404。因此本文不把 PyPI 當成可用入口。固定 HEAD 的 book-to-skill --help 也會警告 unknown flag、沒有顯示 help，與 issue #95 一致；這是目前的 CLI UX bug。

最值得閱讀的關鍵程式碼

SKILL.md 才是真正的產品核心

Python package 只做 extraction。真正決定 cost gate、depth、chapter output、topic index、fold-in 與 security scan 的，是 SKILL.md。評估專案時不能只 review Python。

Parser dispatch 與 batch resilience

book_to_skill/utils.py 能看到格式分派、fallback、單檔失敗隔離、sanitization、metadata 與 source boundaries 的真實順序。

PDF parser 的品質取捨

book_to_skill/parsers/pdf.py 顯示 technical 和 text mode 不是只有速度差異。Docling 保留結構但慢、關閉 OCR；pdftotext 很快，卻可能破壞 table、code，naive dehyphenation 也可能把合法複合字合併錯誤。

Sanitizer 與 generated-skill scanner

sanitize.py 移除不可見 Unicode；scan_generated_skill.py 檢查常見 instruction override、fake system／tool tags、authority-widening frontmatter、exfiltration-shaped content、symlink 與檔案大小。這是 defense in depth，不是通用 prompt-injection 解法。

和 RAG、NotebookLM、MarkItDown 有什麼差異？

工具／做法 主要工作 比較適合
Microsoft MarkItDown 將多種文件轉成結構化 Markdown 需要可靠中間格式，後續 pipeline 自己控制
RAG Query time 找相關 chunks，常搭配 embedding、reranking 與 citation 大量文件、廣泛搜尋、需要回到來源
NotebookLM 以使用者 sources 為 grounding 的研究與問答工作區 多來源探索、inline citation、study material
book-to-skill Compile time 將少量文件重寫成 framework、decision rules 與 on-demand chapters 反覆套用同一本書的方法，並要整合進 coding／writing agent

book-to-skill 官方說 RAG 是 retrieval、skill 是 reasoning，方向上能說明產品差異，卻不應把成熟 RAG 簡化成 keyword search。RAG 可以有 hybrid retrieval、reranking 與 citations；skill 也可能因生成錯誤而失真。

真正的選擇標準是問題形狀：

  • 問「哪一份文件哪裡提到 X」：retrieval 比較自然。
  • 問「用作者的 12 個 framework 幫我做決策」：預先編譯的 skill 比較方便。
  • 只問一次：直接讀原文或放入 context 最簡單。
  • 需要 page-level 可稽核證據：預設 book-to-skill template 不夠，必須自訂 source anchors。

成熟度與已知限制

2026 年 8 月 3 日 22:11（Asia/Taipei）查核時，GitHub API 顯示 15,745 stars、1,690 forks；repository 建立於 2026 年 5 月 1 日，最新 HEAD 是 7 月 31 日的 b74286d，最新 release 是 7 月 30 日的 v1.3.0。

專案把 converter 稱為 stable、multi-format，HEAD 的 CI 在 Python 3.9～3.13、ruff、dependency-free smoke、Bandit、Zizmor、skill validation 與 CodeQL 都通過。本次研究也在乾淨 venv 執行 188 tests passed，並用純文字輸入成功產生兩個中間檔。這些是很好的工程訊號，但不等於 end-to-end knowledge fidelity 已被保證。

目前仍有幾個採用前必須知道的問題：

  • Issue #91 指出 Docling 產生的 Markdown chapter heading 可能不被 detector 正確辨識，實際案例會把章數嚴重高估。
  • Chapter detector 對裸標題與特殊排版仍可能失敗。
  • OCR-heavy scan 不適合目前關閉 OCR 的 technical mode。
  • 預設輸出沒有要求每個結論附 page／section citation。
  • Master skill 本身仍有約 4,000 tokens 的 activation cost。
  • PyPI 404、--help bug 與 HEAD 比 release 多 commit，表示安裝體驗仍在快速整理。

因此我的成熟度判斷是：extractor 已有實質測試與安全 hardening，適合個人或受控團隊試用；生成品質、安裝與大量自動發布仍是早期階段，不應只因 stars 和綠色 CI 就當成企業知識平台。

安全、隱私與著作權

文件會變成未來反覆載入的指令供應鏈

不可信文件先進 parser，再進 Agent context，最後可能成為其他 Agent 反覆載入的 skill。這比一次性 prompt injection 更持久。

專案目前會移除特定 invisible Unicode、拒絕 DOCX 中的 DTD／entity、把交給 subprocess 的 path 轉成 absolute，並在輸出後跑規則式 scanner。這些措施值得肯定，但 visible prompt injection、改寫後的惡意語意或其他語言仍可能漏過；scanner non-zero 的正確處理是停下來人工 review，不是宣告安全。

Local extractor 不代表整條流程都 local

Python extractor 本身不需要上傳文件，也不是 network service；第二階段卻由 host agent 和所選模型執行。如果模型在雲端，抽取文字仍可能受 provider 的保存與訓練政策約束。內部文件、客戶資料與 private code 不應在沒有資料治理評估時送入流程。

中間檔可能洩漏本機資訊

full_text.txt 的 source banner 與 metadata.json 會包含來源 absolute path。它們適合留在受控 temp directory，不應直接公開、貼到 issue 或 commit。

Converter 的 MIT 不等於書籍可以再散布

Repository 採 MIT License，但這只涵蓋 converter。輸入書籍仍受原著作權、授權與公司政策約束。把買來的書轉成個人 skill，和把完整生成物公開給他人下載，是不同的法律與授權情境；官方也提醒不要散布由第三方著作生成的 skill。Copyright 說明

採用前怎麼評估？

建議先做一個小型 PoC：

  1. 選擇自己有權處理、章節清楚的一份技術文件。
  2. 固定 release 或 commit，建立獨立 Python environment。
  3. 只抽 1～2 章，比較 Docling 與 text mode 的 table、code、heading 品質。
  4. 檢查 metadata 的 chapter count 和 ToC，不合理就先人工修正。
  5. 生成後執行 scanner，逐一人工 review findings。
  6. 抽樣 10～20 個重要 framework，回到原始 page／heading 檢查名稱、條件、步驟、例外和 anti-pattern。
  7. 用相似名詞、矛盾章節、超出來源範圍與惡意文字測試 Agent。
  8. 團隊共用前，補 source version、generated date、page anchors、reviewer 和 change log。

不適合直接無人值守採用的情境，包括法律、醫療、金融、資安與 compliance 文件；來源不明或刻意可能含 injection 的資料；不能進 cloud model 的文件；以及需要 OCR、逐句 citation 或大規模跨書搜尋的任務。

研究後的個人結論

book-to-skill 最有意思的地方，是把文件處理拆成 deterministic extraction 和 spec-driven knowledge compilation，並利用 Agent Skills 的 progressive disclosure，把一本書變成核心索引加上按需章節。SKILL.md 對 cost gate、depth、worked example、large-book bounded reads、fold-in 和 output scanning 的要求，明顯比「幫我摘要這本書」完整。

但 parser 的 188 個測試全綠，仍不能保證 Agent 沒有漏掉 caveat、重建錯 worked example 或產生無來源的 framework。查核時存在的 chapter bug、PyPI 404 與 CLI help 問題，也顯示它仍在快速演進。

我的採用結論是：個人學習、開源規範、內部 runbook 和可人工 review 的技術文件，可以固定 commit 後試用；需要 citations、權限隔離、資料治理與高風險正確性的場景，應把它當成生成草稿層，外加 source anchors、locked dependencies、sandbox、review workflow 與定期 revalidation，而不是取代原始文件或正式知識庫。

參考資料