如何把技術書籍轉成 agent skill?
將 PDF、EPUB、DOCX 或內部文件資料夾轉成 agent skill,了解安裝方式、token 預算、headless 執行與 MIT 授權限制。
將技術書轉換為 agent skill:你會得到什麼
若要將技術書轉換為 agent skill,只要讓轉換器處理 PDF、EPUB、DOCX 匯出檔,或你已擁有的內部文件資料夾即可。轉換器會建立一個 skill 目錄:其中包含一個入口檔案,存放已命名的 framework 及章節索引;每章則各有一個檔案,agent 只有在問題需要時才會讀取。整本書不會載入 context window,但索引會載入。
這與 從頭撰寫 agent skill 的工作相反;後者是將你已經熟悉的程序編碼。此處的知識雖然存在,卻無人能夠存取:可能是 800 頁的供應商 PDF,也可能是作者離職後就再也沒有人開啟過的手冊。這項工作的重點是壓縮與建立索引。如果你不熟悉 skill 一詞,請先閱讀 agent skill 的實際定義。
本節使用的轉換器是 book-to-skill,這是一個在你自己的電腦上執行、採用 MIT 授權的 skill。截至 October 2026,最新 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 上安裝轉換器,並固定使用特定版本
此技能是一個 git repository。將它複製到所使用 agent 的 skills 目錄。目錄名稱會成為 slash command,因此複製路徑不能任意指定。
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,不會取得後續版本。請固定版本,因為技能是 agent 遵循的一組指示;未經審查的指示變更,等同於變更伺服器上執行的內容。GitHub Copilot CLI 改為讀取 ~/.copilot/skills/,Amp 則讀取 ~/.agents/skills/。
此外,也有單行安裝方式 npx skills add virgiliojr94/book-to-skill,會取得目前版本。請使用它試用工具。之後需要重新執行時,請使用固定版本的複製內容。
現在確認此主機具備哪些 extractor:
cd ~/.claude/skills/book-to-skill
python3 scripts/extract.py --check--check 會列出已安裝的 extractor,並針對缺少的項目顯示安裝方式:缺少的 Python 套件會整合成一個 pip 指令,缺少的系統工具則各自顯示提示。此套件需要 Python 3.9 或更新版本。
如果複製後在自動完成中沒有出現 /book-to-skill,請執行 /reload-skills 或重新啟動 agent。Claude Code 會監看工作階段啟動時已存在的技能目錄,因此兩分鐘前建立的 ~/.claude/skills/ 目前尚未受到監看。
實際需要哪些擷取器?
除了 Python 以外不需要其他必要元件,因為每種格式都有標準函式庫的備援方案。這些備援方案效能較差;在小型伺服器上,真正浪費時間的是安裝用不到的擷取器。
pdftotext來自poppler-utils套件,適合文字內容較多的 PDF,幾乎可立即完成處理。使用sudo apt install poppler-utils安裝。pypdf和pdfminer.six是 PDF 的 Python 備援方案。docling適合內容價值在表格與程式碼清單中的技術 PDF。該專案測得的速度約為每頁 1.5 秒。ebooklib搭配beautifulsoup4可正確讀取 EPUB。沒有這兩者時,工具會改用標準函式庫的zipfile讀取器。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 會將系統 Python 標記為由 apt 管理,因此 pip 拒絕寫入其中。有兩種可行方式。sudo apt install poppler-utils 會安裝 binary,完全不需要 pip;pdftotext 則可獨立處理大多數散文類 PDF。對於 Python 擷取器,請建立 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固定版本的 v1.4.0 checkout 宣告了 extras pdf、epub、docx、rtf、technical 和 all,其中 technical 是 docling。該專案的安裝頁面也說明如何直接從 GitHub 進行獨立的命令列安裝:pip install "book-to-skill[pdf,epub,docx] @ git+https://github.com/virgiliojr94/book-to-skill.git",接著使用 book-to-skill --check 列出已安裝的擷取器。這不需要 PyPI release,但會安裝專案的 default branch,而不是 v1.4.0,而且只會提供擷取器 command,不會提供 /book-to-skill skill。若要固定版本,請如上所述從自己的 checkout 安裝。單獨執行 pip install book-to-skill 不會成功,因為截至 October 2026,該名稱尚未以此名稱發布到 PyPI。
先不要安裝 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。
互動式執行會逐項提問。系統會詢問資料是否偏技術性或以文字為主,藉此決定擷取器;也會詢問 skill 應協助完成的工作,藉此設定參考或研讀深度,以及各章的預算。接著系統會詢問 skill 的名稱;若尚未建立 skills root,或目前有多個 skills root,還會詢問應使用哪個 root。產生內容前,系統也會顯示 token 與時間預估,並等待確認。
無互動式執行沒有人回答這些問題。可由使用者叫用的 skill 也能在 claude -p 中運作:將 slash 命令放在 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 下的暫存工作目錄;執行的最後一步會刪除該目錄。擷取失敗的來源會略過,因此批次作業仍可完成;這表示即使讀取的檔案少於提供的數量,執行結果仍可能回報成功。請將最終報告中的檔案清單與資料夾內的內容比對。缺少章節通常表示缺少來源。
請將執行作業交給你願意讓代理程式使用的伺服器。在 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 授權涵蓋轉換器的程式碼與技能定義,但不涵蓋你提供給它的文件。
- 你在自己控制的硬體上,使用購買的書籍執行轉換器,屬於從自己的副本製作筆記。
- 發布結果屬於散布,而工具採用 MIT 授權並不授予你散布他人書籍衍生內容的權利。
- 輸出內容屬於衍生著作。架構與章節重點仍受到來源內容塑造,而衍生著作仍受來源著作權規範。
- 以不得再散布的材料建立的技能,應保留在建立它的機器上。不要放入公開儲存庫,也不要放入共用的團隊市集。
- 只有在來源內容屬於你,或採用允許再散布的開放授權時,才應發布,例如團隊撰寫的文件,或授權條款允許再散布的標準。
工具的設計即以此為前提。工具不包含任何書籍內容,且擷取作業會在本機執行。固定的 v1.4.0 只會選擇性輸出一行 gh skill publish,不會詢問可見性,因此決定完全由你負責。專案的預設分支後來加入發布步驟,會以獨立的一字問題詢問儲存庫可見性,只有在回覆是單獨的 public 時才會建立公開儲存庫;其他任何回覆都會設為私人。請將該步驟視為授權決定,因為它實際上就是授權決定。
內部手冊還有另一個問題。這類文件包含認證資料的頻率往往高得令人意外,而轉換器會把無人開啟的 PDF 轉成代理程式可依需求讀取的檔案。提交前,請先完整讀過產生的檔案一次,並參閱避免讓秘密資料進入 AI 代理程式。
一次轉換的成本是多少?
以下數據是專案自行發布的測量結果,不是我們測得的數據。
此圖表背後的資料
[
{
"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 上測量,使用 tiktoken 取得 token 數量,並透過 cl100k_base 計算;截至 2026 年 10 月,數據已發布於專案的 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 等明確標題及其語言變體,也能辨識 Chapter IV 或 IV. Title 等羅馬數字。使用無編號、只有標題的書籍會導致分割結果錯誤。修正方式是告訴執行程序章節的起始位置,不要期待它自行猜測。
找不到該命令。 自動完成功能中缺少 /book-to-skill,表示 skills 目錄是在工作階段開始後才建立的。請執行 /reload-skills,或重新啟動 agent。
Docling 執行時間過長。 每頁約需 1.5 秒,長篇書籍會耗用數分鐘的 CPU 時間。在共用伺服器上,這項工作也會與其他託管的服務競用資源。執行程序詢問內容類型時,請回答「text-heavy」;如果自行執行 scripts/extract.py,則傳入 --mode text。--mode technical 是選取 docling 的答案。
來源檔案悄悄消失。 無法讀取的檔案會被略過,讓批次作業可以完成。之後執行程序會回報成功,但處理的來源數量少於你提供的數量;只有最終報告中的檔案清單會顯示這項差異。將完成的執行結果與實際提供的內容核對,是適用於其他工作的良好習慣;unlazy skill 的 Depth Tree 方法則能要求 agent 遵循相同標準,避免過早宣告工作完成。
手動套用相同模式
這項工具只是便利功能。可移植的是結構,而文字編輯器能為你擁有的任何參考資料建立這種結構。
- 撰寫一個入口檔案,並將其維持在接近轉換器目標的 4,000 tokens。將具名概念及其精確表述寫入其中,並加入索引,列出每個詳細資料檔案及該檔案涵蓋的主題。
- 將資料分割成每個約 1,000 tokens 的檔案,每個檔案只包含一個主題。命名時應讓檔名本身就能說明檔案內容。
- 在入口檔案中描述每個檔案,並寫在說明何時讀取該檔案的句子中。
人們最常略過第 3 步,但這正是模式能運作的關鍵。agent 會讀取索引來決定要開啟哪些檔案,因此索引未描述的檔案,agent 永遠不會開啟。索引就是成果,章節檔案則是儲存內容。
讓入口檔案維持在 compaction budget 內,整個結構就能支撐長時間的工作階段。無論檔案是由 converter 建立,還是由你親自建立,這項規則都成立。
FAQ
我可以發布由購買書籍建立的 skill 嗎?
不可以,除非該書籍的授權條款允許再散布。轉換器採用的 MIT license 僅涵蓋轉換器程式碼,不涵蓋你提供給它的內容,而產生的 skill 是該書籍的衍生作品。請將它保留在自己電腦上的 ~/.claude/skills/。你自行撰寫的文件或採用開放授權的來源則可以發布。固定的 v1.4.0 從不詢問可見性;專案的預設分支現在會將可見性列為獨立問題,只有在填入單獨的 public 時才會公開。因此,無論採用哪種方式,都應由你審慎決定。
我需要 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,啟用它,在其中安裝擷取器,然後從同一個 shell 啟動 agent。該 skill 會呼叫 python3,因此使用 PATH 中的 interpreter;此時該 interpreter 就是 virtual environment 中的版本。
為什麼我產生的 skill 沒有顯示為斜線指令?
有兩個原因。指令名稱來自目錄名稱,因此 skill 必須位於 ~/.claude/skills/<name>/SKILL.md 或 .claude/skills/<name>/SKILL.md,且 SKILL.md 必須完全按照這樣拼寫。如果路徑正確,請執行 /reload-skills 或重新啟動 agent。Claude Code 會擷取已在監看中的 skill 目錄內的修改,但在工作階段開始後才建立的 skills 目錄,在執行上述操作前完全不會被監看。