如何把技術書籍轉成 agent skill？

將技術書籍轉換為 agent skill：可獲得的結果

若要將技術書籍轉換為 agent skill，只要讓轉換工具處理 PDF、EPUB、DOCX 匯出檔，或您已擁有的內部文件資料夾即可。工具會建立一個 skill 目錄：其中包含一個入口檔案，存放已命名的框架與章節索引；每章則各有一個檔案，只有在問題需要時，agent 才會讀取該檔案。書籍內容不會進入 context window，但索引會。

這項工作與從零開始撰寫 agent skill相反，後者是將您已經熟悉的程序編碼。這裡的知識已經存在，但無人能夠取得：可能是一份 800 頁的廠商 PDF，也可能是自撰寫者離職後就未再開啟的手冊。這項工作的重點是壓縮與建立索引。如果您不熟悉 skill 一詞，請先閱讀agent skill 的實際定義。

本節使用的轉換工具是 book-to-skill，這是一個在您自己的機器上執行、採用 MIT 授權的 skill。截至 2026 年 8 月，目前的 tag 是 v1.4.0。工具本身不如它產生的結構重要；FAQ 前的最後一節會說明如何手動建立相同的結構。

為什麼 token 預算是整體設計的核心

將整本書貼入 context window 後，每次需要這本書的對話都必須負擔完整大小的成本。Skill 只需載入一次 entry file，之後再載入問題實際涉及的章節即可。此專案會為產生的每個檔案訂定預算。

[
  {
    "label": "SKILL.md entry file",
    "tokens": "4,000"
  },
  {
    "label": "One chapter file",
    "tokens": "1,000"
  },
  {
    "label": "glossary.md",
    "tokens": "1,500"
  },
  {
    "label": "patterns.md",
    "tokens": "2,000"
  },
  {
    "label": "cheatsheet.md",
    "tokens": "1,000"
  }
]

Entry file SKILL.md 的上限為 4,000 tokens，其中包含指定的 frameworks 與章節索引。每個章節檔案約為 1,000 tokens，會保留在磁碟上，直到有要求讀取。支援檔案的規模也相近：glossary.md 為 1,500 tokens，patterns.md 為 2,000，cheatsheet.md 為 1,000。

這些預算符合 Claude Code 實際使用 context 的方式。Skill 的 description 會列在 skill listing 中，讓模型知道該 skill 存在。Skill 被呼叫時才會載入本文；載入後會在本次 session 的其餘時間留在 context 中，因此 entry file 的每一行都會產生持續成本。支援檔案只有在 agent 讀取時才會載入，因此將內容分成各章節檔案能降低成本。

Entry file 的數字上限背後還有更嚴格的限制。auto-compaction 摘要長對話時，Claude Code 會在摘要後重新附加每個 skill 最近一次的呼叫內容，並在所有重新附加的 skill 之間共用 25,000 tokens 的預算；每個 skill 最多保留前 5,000 tokens。若 entry file 不超過 5,000 tokens，壓縮後仍能完整保留。若 entry file 有 20,000 tokens，恢復時只會保留前四分之一，而且不會告訴你遺失的是哪三個四分之一。

這就是 progressive disclosure：索引保持精簡，始終值得其成本；大量內容則放在 agent 主動開啟的檔案中。Claude Code 如何管理其 context window 說明其餘的計算方式。

在 VPS 上安裝 converter，並固定使用指定版本

此 skill 是 Git repository。將它複製到所使用 agent 的 skills 目錄中。目錄名稱會成為 slash command，因此 clone 路徑不是任意決定的。

git clone --depth 1 --branch v1.4.0 \
  https://github.com/virgiliojr94/book-to-skill.git \
  ~/.claude/skills/book-to-skill

--branch 接受 tag，因此這會 checkout v1.4.0，不會包含之後的內容。請固定版本，因為 skill 是 agent 遵循的一組指示；若未審查的變更修改了這些指示，就等於修改伺服器上執行的內容。GitHub Copilot CLI 則讀取 ~/.copilot/skills/，Amp 讀取 ~/.agents/skills/。

另外也有單行安裝指令 npx skills add virgiliojr94/book-to-skill，會取得目前最新版本。可用它測試工具；任何需要重新執行的操作，都應使用固定版本的 clone。

現在確認這台主機具備哪些 extractors：

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

--check 會列出已安裝的 extractors，並為每個缺少的 extractor 顯示安裝指令。此套件需要 Python 3.9 或更新版本。

如果 clone 後在 autocomplete 中沒有出現 /book-to-skill，請重新啟動 agent。Claude Code 會監看工作階段開始時已存在的 skill 目錄，因此兩分鐘前建立的 ~/.claude/skills/ 目前尚未受到監看。

實際需要哪些 extractor？

除了 Python 之外不需要其他必要元件，因為每種格式都有 standard library fallback。這些 fallback 的效能較差；對小型伺服器而言，真正浪費時間的是安裝用不到的 extractor。

• pdftotext 來自 poppler-utils 套件，可處理文字內容較多的 PDF，幾乎立即完成。使用 sudo apt install poppler-utils 安裝。
• pypdf 和 pdfminer.six 是 PDF 的 Python fallback。
• docling 適合內容價值集中在表格與程式碼清單的技術文件 PDF。專案測得的速度約為每頁 1.5 秒。
• ebooklib 搭配 beautifulsoup4 可正確讀取 EPUB。沒有這些元件時，工具會退回使用 standard library 的 zipfile reader。
• python-docx 可讀取 DOCX，striprtf 可讀取 RTF。
• MOBI 和 AZW 檔案需要 Calibre 的 ebook-convert。
• ocrmypdf 會對完全沒有文字層的掃描書籍執行 OCR（光學字元辨識）。

在 Ubuntu 24.04 上，直接執行 pip3 install pypdf 會顯示：

error: externally-managed-environment

這不是 pip 損壞。Ubuntu 和 Debian 將 system Python 標記為由 apt 管理，因此 pip 拒絕寫入其中。有兩種可行作法。sudo apt install poppler-utils 會安裝 binary，完全不需要 pip；pdftotext 則可自行處理大多數散文類 PDF。對於 Python extractor，請建立 virtual environment，並從其中啟動 agent。如此一來，skill 呼叫的 python3 就是已安裝這些套件的 interpreter。

python3 -m venv ~/.venvs/book-to-skill
source ~/.venvs/book-to-skill/bin/activate
pip install "$HOME/.claude/skills/book-to-skill[pdf,epub,docx]"
claude

該 repository 宣告了 extras pdf、epub、docx、rtf、technical 和 all，其中 technical 是 docling。專案的安裝頁面也列出 pip install "book-to-skill[pdf,epub,docx]"，但截至 August 2026，該名稱尚未發布至 PyPI，因此請如上所述從自己的 checkout 安裝。

在書籍確實需要之前，請不要安裝 docling。它會帶入 machine learning stack，因此在小型方案上安裝前，請先確認可用磁碟空間。

在文件資料夾上執行，包含無人值守模式

此命令可接受單一檔案、資料夾、加上引號的 glob，或一次傳入多個路徑，後面再接選用的 skill 名稱。只要能放入同一個目錄的內容都可以處理，包括 RFC 集合（request for comments，定義網際網路通訊協定的文件）。

/book-to-skill ~/library/platform-docs/ platform-handbook
/book-to-skill "~/books/*.epub" my-library
/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-research

請為 glob 加上引號，避免 shell 在 skill 讀取前先將其展開。若將命令指向現有的 skill 目錄，新來源會併入該 skill，而不是建立第二個 skill。

互動式執行會向你提問。資料屬於技術內容或文字密集內容，這會決定使用的擷取器。你需要 reference depth 還是 study depth，這會決定每章的預算。skill 應使用什麼名稱，以及應放入哪個 skills root。生成前，命令也會顯示 token 與時間估算，並等待你確認。

無人值守執行時沒有人回答這些問題。使用者可叫用的 skill 確實能在 claude -p 中運作：將 slash command 放入 prompt 字串，Claude Code 會在執行開始前展開它。因此，請在同一個 prompt 中回答這些問題。

claude -p "/book-to-skill ~/library/platform-docs/ platform-handbook
The sources are technical. Use reference depth. Write the skill to
~/.claude/skills/. Do not publish it to GitHub. Proceed without asking me." \
  --allowedTools "Bash,Read,Write,Edit"

--allowedTools 會預先核准執行所需的工具，因為沒有終端機可供回應的權限提示，會使執行永遠無法完成。加入 --output-format json 會在結果中加入 total_cost_usd；這是用戶端估算值，不是你的計費量。

在任何模型讀取來源前，擷取程序會將所有來源整合至 /tmp 下的暫存工作目錄。執行最後一步會刪除該目錄。擷取失敗的來源會被略過，因此批次仍可完成；這表示執行報告成功時，實際讀取的檔案可能少於你提供的數量。請將最終報告中的檔案清單與資料夾內容比對。缺少章節通常表示缺少來源。

請為此次執行提供一台你願意讓 agent 使用的伺服器。在 VPS 上安全地執行 Claude Code 說明權限相關事項。

輸出位置：讓程式碼代理程式找到它

產生的 skill 會放在 skills root 中。其中有兩個位置需要注意。

• ~/.claude/skills/<skill-name>/ 是個人層級的位置，該機器上的所有專案都能使用。
• .claude/skills/<skill-name>/ 位於 repository 內，會隨 repository 一起移動。

這兩個位置中都包含 SKILL.md、一個 chapters/ 目錄，以及每個章節各一個檔案和其他支援檔案。目錄名稱就是 command，因此 ~/.claude/skills/platform-handbook/ 會提供 /platform-handbook；之後可以接續輸入主題或一般問題。

請依授權條件，而非便利性選擇 root。根據你購買的書籍建立的 skill，應放在個人目錄。根據團隊自行撰寫的文件建立的 skill，應放在 repository 中。如此一來，在多個 repository 之間共用同一個 skill 就成為下一個需要解決的問題。

每增加一個 skill，就會增加一項成本。每個 skill 的描述都會保留在 skill listing 中，讓模型判斷是否使用；每個項目的合併描述文字會截斷在 1,536 個字元，而整個 listing 也有容量限制。十個書籍 skill 就代表十個描述必須競爭這項容量。對於你總是以名稱呼叫的 skill，請在產生的 frontmatter 中加入一行：

---
name: platform-handbook
description: Frameworks and chapter index from the internal platform handbook.
disable-model-invocation: true
---

使用 disable-model-invocation: true 後，描述會完全排除在 context 外；當你輸入 /platform-handbook 時，skill 仍會完整載入。代價是無法自動探索，但可以讓 context window 更精簡。

授權：MIT 授權涵蓋轉換器，不涵蓋書籍

請準確理解這一點，因為這裡的問題不是技術問題。

• MIT 授權涵蓋轉換器的程式碼及其 skill 定義。它未對交給轉換器的文件作任何授權。
• 在你控制的硬體上，對自己購買的書籍執行轉換器，屬於根據自己的副本做筆記。
• 發布結果屬於散布，而工具採用的 MIT 授權不會授予你散布他人書籍衍生內容的權利。
• 輸出內容屬於衍生著作。框架與章節重點仍受到來源內容塑造，而衍生著作仍受來源著作權規範。
• 以無法再散布的素材建立的 skill，應留在建立它的機器上。不能放入公開 repository，也不能放到共用的團隊 marketplace。
• 只有在來源內容屬於你，或採用允許再散布的開放授權時，才能發布，例如團隊撰寫的文件，或授權條款允許再散布的標準。

工具的設計即以此為前提。工具不包含任何書籍內容，擷取作業會在本機執行，而發布步驟會另外詢問 repository 的可見性。該步驟只接受單獨的 public 或 private，不會自行推斷。請將這個提示視為授權決策，因為它確實就是授權決策。

內部手冊還有第二個問題。這類文件包含憑證的情況比任何人承認的都更常見，而轉換器會把沒有人開啟的 PDF 轉成你的 agent 可依需求讀取的檔案。提交前，請先完整讀過一次產生的檔案，並參閱 避免讓 secret 出現在 AI agent 中。

一次轉換的成本是多少？

以下數據是專案自行發布的測量結果，不是我們測得的數據。

[
  {
    "label": "Think Python 2",
    "cost_usd": 0.88
  },
  {
    "label": "Working Backwards",
    "cost_usd": 0.96
  },
  {
    "label": "Pro Git",
    "cost_usd": 1.23
  },
  {
    "label": "Moby-Dick",
    "cost_usd": 1.42
  }
]

在專案測量的 4 本書中，每次轉換的成本介於 0.88 至 1.42 美元之間，其中 Pro Git 為 1.23 美元。這些數據是在 Claude Sonnet 4.5 上測得，token 數量來自 tiktoken，使用 cl100k_base 計算，並於 2026 年 8 月發布在專案的 docs/performance.md 中。實際成本會隨使用的模型與價格而變動。

專案也記錄了以下差異：回答 skill 中的單一問題所需的 token，比將整本書貼入 context 少 24 至 51 倍。這應視為節省幅度的概況，而不是保證值，因為結果取決於書籍與問題內容。但結構上的結論不變：轉換成本只需支付一次，而 context dump 則會在每次需要該書的對話中再次產生成本。

為什麼不直接貼上 PDF，或建立 RAG 索引？

貼上內容可行，而且對於針對單一文件提出單一問題而言，這是正確做法。當同一本書在星期二需要使用，星期五又再次需要使用時，這種做法就不再合適，因為每次都必須支付完整內容的大小成本。

Retrieval，或稱 RAG（retrieval augmented generation），會在查詢時進行搜尋，並傳回符合查詢文字的段落。當你需要精確句子時，這種方式很有效。但如果有用的內容是分散在整個章節中的架構，這種方式就較弱，因為沒有任何單一段落包含完整架構。Skill 會在轉換時進行一次這項擷取，並儲存結構，而不是儲存段落。

必須坦白說明其限制：產生的 skill 是由模型撰寫的有損摘要。它可作為研讀輔助，但來源仍是來源文件。當精確措辭涉及法律效力或協定規範時，請保留 PDF，並直接引用其中內容。Skills 與 MCP servers 及 rules files 的比較說明各種方法適用的情境。

失敗模式與你會看到的字串

掃描 PDF 沒有產生任何內容。 擷取器會檢查開頭幾頁是否有文字層。如果沒有，便會附上說明後停止，不會持續處理 400 頁的影像。先執行 ocrmypdf input.pdf output.pdf，再將輸出檔案提供給它。

pip 拒絕安裝。 Ubuntu 24.04 上的 error: externally-managed-environment 是 apt 保護系統 Python 的機制。請使用上方的虛擬環境，或安裝 poppler-utils，完全略過 pip。

章節內容錯誤。 章節偵測會尋找 Chapter 7 等明確標題及其語言變體。若書籍只使用未標記的段落標題或羅馬數字，章節切分就會錯誤。此時應告訴執行程序章節的起始位置，不要依賴自動猜測。

找不到該命令。 自動補全中缺少 /book-to-skill，表示 skills 目錄是在目前工作階段開始後才建立的。請重新啟動 agent。

Docling 執行時間過長。 每頁約需 1.5 秒，因此長篇書籍會耗用數分鐘的 CPU 時間。在共用伺服器上，這項工作也會與你代管的其他服務競用資源。執行程序詢問內容類型時，請回答「text-heavy」；如果自行執行 scripts/extract.py，請傳入 --mode text。選取 docling 的答案是 --mode technical。

來源檔案無聲消失。 無法讀取的檔案會被略過，讓批次工作可以完成。接著，執行程序會回報成功，但處理的來源數量少於你提供的數量；唯一會顯示這項差異的地方，是最終報告中的檔案清單。

手動套用相同模式

這項工具只是便利功能。可移植的是結構，而文字編輯器能為你擁有的任何參考資料建立這種結構。

1. 撰寫一個入口檔案，並將其維持在接近轉換器目標的 4,000 tokens。將具名概念及其精確表述寫入其中，並加入索引，列出每個詳細資料檔案及該檔案涵蓋的主題。
2. 將資料分割成每個約 1,000 tokens 的檔案，每個檔案只包含一個主題。命名時應讓檔名本身就能說明檔案內容。
3. 在入口檔案中描述每個檔案，並寫在說明何時讀取該檔案的句子中。

人們最常略過第 3 步，但這正是模式能運作的關鍵。agent 會讀取索引來決定要開啟哪些檔案，因此索引未描述的檔案，agent 永遠不會開啟。索引就是成果，章節檔案則是儲存內容。

讓入口檔案維持在 compaction budget 內，整個結構就能支撐長時間的工作階段。無論檔案是由 converter 建立，還是由你親自建立，這項規則都成立。

FAQ

我可以發布由購買書籍製作的 skill 嗎？

不可以，除非該書的授權條款允許再散布。converter 採用的 MIT license 僅適用於 converter 的程式碼，不適用於您提供給它的內容，而產生的 skill 是該書的衍生著作。請將它保留在自己機器上的 ~/.claude/skills/ 中。您自行撰寫的文件或採用開放授權的來源可以發布；此外，工具會另外詢問 repository visibility，且只接受單獨的 public 或 private，因此能讓您審慎決定。

我需要 docling，還是 pdftotext 就足夠？

poppler-utils 中的 pdftotext 足以處理一般文字，而且幾乎立即完成。若書籍的價值在於表格和程式碼列表，請安裝 docling，因為純文字擷取工具會剛好遺漏這些內容。代價是速度：專案測得 docling 每頁約需 1.5 秒，因此 300 頁的手冊在 VPS 上需要數分鐘的 CPU 時間。

為什麼 pip 在我的 VPS 上因 externally-managed-environment 而失敗？

Ubuntu 24.04 和目前版本的 Debian 會將系統 Python 標記為由 apt 管理，因此 pip 拒絕安裝到其中，並輸出 error: externally-managed-environment。使用 python3 -m venv ~/.venvs/book-to-skill 建立 virtual environment，啟用後在其中安裝 extractors，接著從同一個 shell 啟動 agent。skill 會呼叫 python3，因此使用 PATH 中的 interpreter；此時該 interpreter 位於 virtual environment 內。

為什麼產生的 skill 沒有顯示為 slash command？

有兩個原因。command 名稱取自目錄名稱，因此 skill 必須位於 ~/.claude/skills/<name>/SKILL.md 或 .claude/skills/<name>/SKILL.md，且 SKILL.md 的拼法必須完全相同。如果路徑正確，請重新啟動 agent。Claude Code 會讀取它已在監看的 skill 目錄內的變更，但在工作階段開始後才建立的 skills 目錄，完全不會被監看。