Book to Skill 教學手冊
book-to-skill 教學手冊 book-to-skill — 把一本書、一份文件、甚至一整個 docs/ 資料夾，轉成 AI Agent 可隨查隨用的 「Skill」：Claude Code、GitHub Copilot CLI、Amp 三大 host 共用的知識轉換引擎 適用對象：資深工程師、AI Engineer、知識工程／RAG 團隊、Tech Lead、架構師、企業導入人員、PM 文件性質：企業內部「Knowledge-as-Skill」知識庫導入、開發與維運培訓教材 版本基準：book-to-skill（virgiliojr94/book-to-skill，2026 年 5 月 1 日建立、核心 MIT License、 v1.3.0 正式版於 2026-07-30 發布；本次改版核校時間點 2026-08-04） ⚠️ 重要聲明（請務必先讀） book-to-skill 仍在高速迭代中。 本專案於 2026-05-01 建立，短短三個月內成長迅速，已登上 GitHub Trendshift 趨勢榜（編號 #27038）。截至本次改版核校（2026-08-04，直接呼叫 api.github.com/repos/virgiliojr94/book-to-skill 查證，非憑記憶）已有 16,048 Stars、 1,714 Forks、81 Subscribers、18 個開放 Issue，版本從 v1.0.0（2026-06-08）快速推進到 v1.3.0（2026-07-30，pyproject.toml 版本號同步為 1.3.0，最後一次 push 為 2026-07-31）。 其 CLI 參數、SKILL.md 內部步驟、目錄結構在版本之間可能持續變動，任何指令與檔名在正式導入前， 務必以最新官方 Repository 為準；本手冊所列數字僅為核校當下快照。 本手冊的定位是「理解、彙整、分析、重組、補充最佳實務」，而非官方文件翻譯。 依撰寫要求，本書 不直接翻譯 README、不大量抄錄原文，而是以企業教育訓練教材的角度重新組織、加入架構圖、比較表、 最佳實務與導入建議。 內容分兩類： 官方已確認事實（例如 book_to_skill/ pip 套件結構、scripts/extract.py 薄殼層、 SKILL.md 規格文件本身驅動 Step 0–10 的生成流程、tools/discovery_tax.py／ tools/validate_skill.py／tools/scan_generated_skill.py 三支輔助工具、sanitize.py 的 隱藏字元清洗機制等）作為骨幹，內文一律使用 repo 內實際檔名／路徑／指令，不使用意譯替代。 本次核校已透過 GitHub API 直接讀取 repo 檔案樹、README.md、SKILL.md、 docs/ARCHITECTURE.md、pyproject.toml、book_to_skill/config.py 等原始檔案逐一比對， 非僅憑記憶或二手轉述。 作者補充：凡屬作者依企業（含金融業、保險業）導入 AI Agent 知識工程之實務經驗所補充或推論 之處，會標註 （作者建議） 或 （作者推論）。這些是最佳實務參考，非官方保證。 特別澄清（避免讀者對架構產生誤解）： book-to-skill 不是一個獨立呼叫 Anthropic／OpenAI API 的雲端服務，它本身沒有也不需要 設定任何 LLM API Key——真正執行「閱讀全文、萃取框架、寫出 SKILL.md」這些生成工作的模型， 是使用者當下所在的 host agent（Claude Code、GitHub Copilot CLI、或 Amp）本身。book-to-skill 提供的是一份規格文件（SKILL.md）加一組確定性的文字擷取程式（book_to_skill/ 套件），並不是 另一個會發送 API 請求的後端服務。 book-to-skill 不是 MCP（Model Context Protocol）Server，repo 中沒有 MCP 相關程式碼。它遵循 的是另一個開放標準——Agent Skills 標準（agentskills/agentskills），與 MCP 是兩種不同的 擴充機制，兩者可以並存但不是同一件事。第13章會詳細釐清這個常見誤解。 這兩點都與坊間許多「AI 開發工具教學範本」預設的雲端服務／MCP 整合章節不同，本手冊會在對應章節 明確標註「此工具不適用」而非硬套範本。 授權條款請留意「範圍界線」： book-to-skill 轉換器本身（程式碼 + SKILL.md 規格）採 MIT License，可自由商用、修改、內部散布。但這不代表經過 book-to-skill 處理過的書籍／文件內容 本身的著作權也隨之開放——官方 README 明確指出：book-to-skill 不隨附任何書籍內容、不上傳使用者的 檔案，產生的 Skill 是「你自己的讀書筆記」性質的衍生摘要，不可對外散布第三方受著作權保護書籍所 產生的 Skill；公司內部文件、自有著作、開放授權素材則可依其授權範圍分享。金融業、保險業等受 監理產業，導入前應將此授權界線一併提交法務／智財單位確認（作者建議）。 官方權威來源請見〈附錄 A・References〉。 目錄（Table of Contents） 圖例與符號說明 本手冊閱讀路徑 第1章 book-to-skill 是什麼 1.1 一句話定義 1.2 發展背景與誕生脈絡 1.3 設計理念 1.4 解決哪些問題：Discovery Loop Tax（核心賣點） 1.5 適用情境 1.6 限制 1.7 特色 1.8 優點 1.9 缺點 1.10 與傳統 RAG 的差異 1.11 與向量資料庫的差異 1.12 與 MCP 的差異 1.13 與「Claude Skills」的關係 1.14 本章 Checklist 與小結 第2章 系統架構 2.1 架構總覽：兩個半部 2.2 資料流（Data Flow） 2.3 Knowledge Flow（知識萃取的分層邏輯） 2.4 Skill Generation Pipeline（SKILL.md 驅動的 Step 0–10） 2.5 Document Processing 決策樹 2.6 Prompt Pipeline：四種操作模式 2.7 端到端資料流總結圖 2.8 本章 Checklist 與小結 第3章 book-to-skill 核心架構詳解 3.1 Parser（解析器） 3.2 Layout Detection（章節／目錄偵測） 3.3 Knowledge Extraction（知識萃取，Agent 側） 3.4 Skill Generator 3.5 Metadata 3.6 Output（輸出結構） 3.7 CLI 3.8 Config 3.9 Cache（誠實說明：沒有持久化快取） 3.10 Log（誠實說明：沒有結構化 Logging 框架） 3.11 Error Handling 3.12 Plugin／Extension（誠實說明：沒有執行期 Plugin 機制，但有明確的擴充路徑） 3.13 本章 Checklist 與小結 第4章 安裝 4.1 兩種安裝路徑，先分清楚再動手 4.2 Windows 安裝 4.3 Linux 安裝 4.4 macOS 安裝 4.5 WSL 安裝 4.6 各 Host 安裝指令對照 4.7 pip 安裝（獨立 CLI） 4.8 uv 安裝（作者建議） 4.9 Node／Git 等前置需求 4.10 企業安裝：Offline 安裝（作者建議） 4.11 Proxy／Firewall 注意事項（作者建議） 4.12 本章 Checklist 與小結 第5章 設定 5.1 設定機制總覽（誠實澄清：沒有 YAML/JSON 設定檔） 5.2 CLI 參數 5.3 環境變數 5.4 API Key：明確澄清「不需要設定」 5.5 各 Host 的模型從何而來 5.6 mkdocs.yml：官方文件站設定（非使用者需設定項） 5.7 最佳設定建議（作者建議） 5.8 本章 Checklist 與小結 第6章 文件格式支援 6.1 支援格式總表 6.2 PDF：技術書 vs. 文字書的取捨 6.3 EPUB 6.4 DOCX（Office 格式） 6.5 純文字系列（TXT／Markdown／RST／AsciiDoc） 6.6 RTF 6.7 MOBI／AZW／AZW3 6.8 不同企業文件類型的實務對應（作者建議） 6.9 本章 Checklist 與小結 第7章 Document Parsing 與 Layout Analysis 深入 7.1 Layout Analysis 總覽 7.2 章節辨識（Heading Detection） 7.3 Table／Code Block 擷取 7.4 Image／Caption／Footnote／Reference／Citation 的處理限制（誠實說明） 7.5 安全防護：文件→Context 供應鏈的三道防線 7.6 最佳實務 7.7 本章 Checklist 與小結 第8章 Knowledge Extraction（知識萃取） 8.1 Step 3：分析書籍結構（回顧與展開） 8.2 Step 4：詢問用途，推導 DEPTH 8.3 Quality Rules：八條品質準則（重新詮釋） 8.4 六種知識形態與模板欄位對照 8.5 案例：如果把經典架構書丟進 book-to-skill 8.6 本章 Checklist 與小結 第9章 Skill Generation（Skill 產出規格） 9.1 SKILL.md 主檔模板結構 9.2 Cross-agent 相容性設計（agent-neutral 寫法） 9.3 chapters/ch<NN>-<slug>.md 模板逐節說明 9.4 支援檔案：glossary／patterns／cheatsheet 9.5 Update／Fold-in Workflow（Mode 4）深入 9.6 本章 Checklist 與小結 第10章 Claude Code 如何使用 10.1 安裝與基本使用回顧 10.2 與 Claude Skills 機制的關係 10.3 與 CLAUDE.md／Memory 體系整合（作者建議） 10.4 Context 載入行為 10.5 與 Subagent／Agent 架構搭配 10.6 與既有 Workflow／Slash Command 整合 10.7 最佳實務 10.8 本章 Checklist 與小結 第11章 GitHub Copilot CLI 如何使用 11.1 安裝與 Reload 11.2 與 Custom Instructions（copilot-instructions.md）的分工 11.3 Prompt Files 對照（作者建議延伸） 11.4 Project-local 安裝與 Workspace 共用 11.5 Agent Mode 下的行為 11.6 MCP 澄清（延續 1.12 節） 11.7 分享已生成的 Skill 11.8 本章 Checklist 與小結 第12章 其他 Agent CLI 整合（Amp／Codex CLI／Gemini CLI／Cursor／Windsurf／Cline 等） 12.1 官方明確支援：Amp 12.2 Agent Skills 開放標準的官方採用者名單（2026-08-04 查證，非作者推論） 12.3 Agent Skills 標準的正式規格：SKILL.md frontmatter 欄位 12.4 為什麼相容性仍需自行驗證：機制本質差異（已窄化為工具實作細節層級） 12.5 手動整合模式（作者建議，適用 Windsurf／Cline 等尚未支援 Agent Skills 標準的工具） 12.6 AGENTS.md 慣例與 Agent Skills 標準的分工（作者建議） 12.7 本章 Checklist 與小結 第13章 MCP 整合的正確理解 13.1 再次明確澄清 13.2 為什麼這個誤解特別容易發生 13.3 與常見 MCP Server 的分工建議（作者建議） 13.4 本章 Checklist 與小結 第14章 Reverse Engineering 場景應用（作者延伸） 14.1 為什麼逆向工程需要「知識可查詢化」 14.2 適用範圍：官方語言／框架手冊，而非原始碼本身 14.3 與 reverse-skill 的分工建議（作者建議） 14.4 案例走查：PowerBuilder 老系統維運知識庫 14.5 最佳實務 14.6 本章 Checklist 與小結 第15章 Framework Upgrade 場景應用（作者延伸） 15.1 為什麼框架升級特別適合這個模式 15.2 各框架 Migration Guide 轉 Skill 對照 15.3 案例：Spring Boot Migration Guide → Skill → 升級專案查詢 15.4 最佳實務 15.5 本章 Checklist 與小結 第16章 大型 Web Application 知識庫應用 16.1 官方立場回顧：「Beyond Books」 16.2 把整個 docs/ 資料夾轉成 Skill 16.3 DDD／Microservices／Clean Architecture／Hexagonal 場景應用（作者延伸） 16.4 Review／Testing／Refactoring 場景應用（作者延伸） 16.5 最佳實務 16.6 本章 Checklist 與小結 第17章 AI Agent Workflow／方法論整合（作者延伸） 17.1 book-to-skill 在 AI Agent Workflow 中的定位 17.2 與 Spec Driven Development 系列方法論整合（作者建議） 17.3 與 Multi-Agent／Council 類方法論整合（作者建議） 17.4 最佳實務 17.5 本章 Checklist 與小結 第18章 企業導入治理（Governance） 18.1 Governance 總覽 18.2 版本管理（Version） 18.3 Knowledge Base／Repository 存放策略 18.4 Review：validate_skill.py 深度用法 18.5 Security：scan_generated_skill.py 的治理角色 18.6 Compliance（合規） 18.7 Audit（稽核軌跡，作者建議） 18.8 RBAC（誠實說明：無內建機制，需依賴底層存取控制） 18.9 本章 Checklist 與小結 第19章 CI/CD 整合 19.1 book-to-skill 自身的 CI（真實依據） 19.2 企業 CI 中的品質閘門（作者建議） 19.3 GitHub Actions 完整範例 19.4 GitLab CI 範例 19.5 Azure DevOps 範例 19.6 Jenkins 範例 19.7 「自動建立 Skills」的實際可行邊界（誠實說明） 19.8 版本管理／測試／發佈 19.9 本章 Checklist 與小結 第20章 Maintenance（維運） 20.1 Update／Fold-in 維運週期 20.2 book-to-skill 本身的升級 20.3 Backup（備份） 20.4 Migration（搬遷） 20.5 Troubleshooting 20.6 Monitoring／Logging（延續 3.10 節的補強建議） 20.7 Performance／Optimization 20.8 本章 Checklist 與小結 第21章 企業最佳實務（Best Practice） 21.1 大型企業如何使用 book-to-skill：總覽 21.2 知識治理 21.3 文件管理 21.4 版本管理（治理原則，工具操作見19.8節） 21.5 多人協作 21.6 Skill Review（類似 Code Review 的審查流程） 21.7 Quality Gate 21.8 AI Governance 21.9 避免「知識墳場」 21.10 本章 Checklist 與小結 第22章 與其他工具比較 22.1 比較維度說明 22.2 vs. NotebookLM 22.3 vs. 傳統 RAG（展開 1.10 節） 22.4 vs. MCP Memory 類伺服器 22.5 vs. Context7 22.6 vs. Cognee 22.7 vs. codebase-memory-mcp 22.8 vs. OpenMemory（⚠️ 作者依公開資訊之一般性描述，非逐一查證版本細節） 22.9 vs. Knowledge Graph（通用類） 22.10 綜合比較表 22.11 關鍵洞察：book-to-skill 的差異化定位 22.12 本章 Checklist 與小結 第23章 完整案例（作者原創案例走查） 23.1 案例一：保險業 Spring Boot 3→4 升級知識庫建置 23.1.1 背景與任務發起 23.1.2 轉換與查詢過程 23.1.3 效益與知識沉澱 23.2 案例二：製造業 Legacy Java 系統現代化前的知識庫盤點 23.2.1 背景與任務發起 23.2.2 轉換與查詢過程 23.2.3 新人 Onboarding 對照 23.2.4 知識沉澱範本（團隊內部記錄格式示意） 23.3 案例三：新創公司 Vue3 前端設計系統知識庫 23.3.1 背景與任務發起 23.3.2 轉換與查詢過程 23.3.3 效益 23.4 案例四：SI 顧問團隊為客戶 PowerBuilder 老系統做知識移轉 23.4.1 背景與任務發起 23.4.2 轉換與查詢過程 23.4.3 交接效益 23.5 四案例綜合對照 23.6 本章 Checklist 與小結 第24章 完整 CLI 指令大全 24.1 三層 CLI 入口總覽 24.2 pip 獨立 CLI：book-to-skill 24.3 scripts/extract.py（Agent Skill 內部薄殼層） 24.4 tools/discovery_tax.py：Token 成本量測工具 24.5 tools/validate_skill.py：格式合規驗證 24.6 tools/scan_generated_skill.py：安全掃描 24.7 Agent Skill 斜線指令：/book-to-skill（各 Host 內使用） 24.8 CLI Cheat Sheet 總表 24.9 本章 Checklist 與小結 第25章 FAQ 25.1 基礎概念（Q1–Q15） 25.2 安裝與環境（Q16–Q30） 25.3 使用與操作（Q31–Q48） 25.4 格式與解析（Q49–Q60） 25.5 安全與合規（Q61–Q72） 25.6 企業導入與治理（Q73–Q88） 25.7 與其他工具比較（Q89–Q98） 25.8 疑難排解（Q99–Q112） 25.9 本章 Checklist 第26章 常見錯誤（55個） 26.1 安裝與環境類（錯誤 1–8） 26.2 轉換與生成類（錯誤 9–18） 26.3 格式與解析類（錯誤 19–26） 26.4 Skill 品質與內容類（錯誤 27–36） 26.5 安全與合規類（錯誤 37–44） 26.6 企業導入與治理類（錯誤 45–55） 26.7 本章 Checklist 第27章 Prompt Engineering：如何寫出高品質 Skill 27.1 如何對 book-to-skill 下指令 27.2 如何建立高品質 Skill：把 Quality Rules 變成團隊寫作規範 27.3 如何建立大型 Knowledge：分主題整併策略 27.4 如何避免 Hallucination（幻覺） 27.5 本章 Checklist 與小結 第28章 企業導入建議（依產業） 28.1 銀行業 28.2 保險業 28.3 政府部門 28.4 醫療產業 28.5 製造業 28.6 大型系統整合商（SI） 28.7 SaaS 公司 28.8 新創公司（Startup） 28.9 各產業導入要點對照表 28.10 本章 Checklist 與小結 第29章 完整實戰：從一本 PDF 到團隊日常開發流程 29.1 完整流程總覽 29.2 Step 1：取得 PDF 並判斷內容類型 29.3 Step 2：執行轉換 29.4 Step 3：驗證與人工抽查 29.5 Step 4：納入版控與 CI Gate 29.6 Step 5：登記進團隊 CLAUDE.md 29.7 Step 6：Coding 階段查詢輔助設計決策 29.8 Step 7：Code Review 引用 Skill 作為審查依據 29.9 Step 8：Testing 階段依 Anti-patterns 設計測試案例 29.10 Step 9：Deploy 後持續 Fold-in 29.11 本章 Checklist 與小結 第30章 總結與未來發展 30.1 全書核心觀點回顧 30.2 版本演進脈絡與展望 30.3 AI Agent 趨勢與 Skill 生態系 30.4 Knowledge Engineering 的未來 30.5 最佳建議 30.6 學習路線圖 30.7 本章 Checklist 與小結 附錄 A.1 全書核心原則速查 A.2 名詞對照表 A.3 References（參考資料） A.4 新進成員快速上手 Checklist 結語 圖例與符號說明 本手冊沿用企業教材慣例，以下符號在全書中意義固定： ...