書籍轉技能轉換器

透過提取結構（而非產生摘要），將書面知識轉化為可操作的代理技能。

哲學

書籍蘊含結晶化的專業知識：框架、原則和技術，這些都是經年累月發展而成的。此技能將這些知識提取成一種格式，讓 GitHub Copilot CLI、Amp、Claude Code 或其他相容的代理能夠重複利用。

提取結構，而非摘要。 技能不是讀書報告。它是一個由以下組成的工具包：

已命名的框架（具有明確應用場景的心理模型）
可操作的原則（指導決策的規則）
技術（逐步方法）
反模式（應避免的事項及其原因）
語調校準（作者思考和溝通的方式）

保留作者的精確性。 框架的名稱通常有特定的原因。「5 個為什麼」不能與「多次問為什麼」互換。捕捉其確切表述。

適當地分層深度。 簡單的書籍 → 簡單的技能。具有 10 個以上框架的複雜書籍 → 具有參考檔案和隨需章節的技能。

操作模式

有四種路徑可用。根據使用者的要求來選擇：

1. 完整轉換（預設）

觸發條件： 使用者提供一個或多個文件/目錄/glob 路徑，但沒有特殊指示 動作： 執行以下所有步驟（步驟 0–9） 輸出： 包含 SKILL.md、chapters/、詞彙表、模式、備忘錄的完整技能

2. 僅分析

觸發條件： 使用者說「分析」、「僅提取」或「我想在生成前先審閱」 動作： 執行步驟 0–3，然後產生結構化的提取報告（找到的框架、原則、技術）。停止 — 不要生成技能檔案。 輸出： 供使用者審閱的分析報告

3. 從先前的分析生成

觸發條件： 使用者有現有的分析筆記或先前執行過僅分析模式 動作： 跳過步驟 0–3，使用提供的分析作為輸入，執行步驟 4–9 輸出： 根據提供的分析生成技能檔案

4. 更新 / 合併（現有技能）

觸發條件： 使用者提供一個或多個新的來源路徑，並表示它們想要更新現有技能（透過指向現有技能資料夾、提供已存在於 SKILLS_HOME 中的技能 slug，或明確要求更新）。 動作： 執行步驟 0（範圍外檢查）、步驟 1（驗證輸入）、步驟 1.5（識別書籍類型）和步驟 2（提取新檔案）。然後跳至步驟 5（識別/偵測現有技能路徑）並執行更新/合併工作流程，將新內容合併到現有的技能檔案中。 輸出： 包含新的/修訂的章節摘要以及合併的索引/詞彙表的更新現有技能。

技能位置

這個轉換器可以從多個技能系統執行。在尋找此轉換器的輔助腳本或寫入生成的書籍技能時，請依此順序偏好這些位置：

GitHub Copilot CLI 個人技能：~/.copilot/skills/
跨代理個人技能（Copilot + Amp）：~/.agents/skills/
Claude Code 個人技能：~/.claude/skills/
專案本地 Copilot 技能：.github/skills/
專案本地 Claude 技能：.claude/skills/
專案本地 Amp / Copilot 技能：.agents/skills/
Amp 全域技能：~/.config/agents/skills/
Amp 舊版全域技能：~/.config/amp/skills/

對於生成的書籍技能，選擇使用者的主機代理實際上可以發現的目的地（請參閱步驟 5）。當存在多於一個有效的根目錄時，請詢問使用者一次並在整個工作階段中記住答案 — 不要靜默地使用預設值。

步驟 0 — 範圍外檢查

如果未提供任何參數，則停止並回應：

"book-to-skill 需要一個支援的文件路徑、資料夾或 glob 模式。用法：book-to-skill <路徑到文件資料夾或-glob>... [skill-name-slug]"

在整個工作流程中：

識別輸入路徑和可選的技能 slug。
如果最後一個參數不是一個存在的檔案、資料夾或可匹配任何檔案的 glob，並且它看起來像一個技能 slug（例如小寫連字符，字母數字），則將其視為 SKILL_NAME。
將所有其他參數視為 INPUT_PATHS 列表。
如果任何輸入路徑是現有的技能目錄（包含 SKILL.md 和 chapters/ 子資料夾），或者 SKILL_NAME 與 SKILLS_HOME 中的現有技能 slug 匹配，則將此執行標記為更新/合併操作（模式 4）。

步驟 1 — 驗證輸入

驗證 INPUT_PATHS 中至少有一個支援的檔案、目錄或 glob 模式。對於目錄和 glob，展開它們以找到匹配的支援檔案（.pdf, .epub, .docx, .txt, .md, .markdown, .rst, .adoc, .html, .htm, .rtf, .mobi, .azw, .azw3）。

如果未找到支援的檔案，則停止並顯示清晰的錯誤訊息。

步驟 1.5 — 識別內容類型

在提取之前，詢問使用者：

"這些來源有什麼類型的內容？這有助於我選擇最佳的提取方法。

技術類 — 包含程式碼區塊、表格、公式、圖表（例如程式設計書籍、學術論文、架構指南）

文字為主 — 主要是散文，很少或沒有表格/程式碼（例如管理學、生產力、敘事性非小說）

不確定 — 我將使用快速方法，並在品質看起來有限時警告您"

將答案儲存為 BOOK_TYPE：

選項 1 → BOOK_TYPE=technical
選項 2 → BOOK_TYPE=text
選項 3 → BOOK_TYPE=text

如果 BOOK_TYPE=technical，在繼續之前通知使用者：

"📐 已選擇技術模式 — 使用 Docling 進行結構感知提取（表格、程式碼區塊、公式保留為 markdown）。這大約需要每頁 1.5 秒，因此對於較長的來源預計需要幾分鐘。現在開始…"

如果 BOOK_TYPE=text，通知：

"📄 已選擇文字模式 — 對每種檔案類型使用最快的合適提取器。純文字/Markdown/HTML 通常在幾秒內準備就緒；PDF 在可用時使用 pdftotext。"

步驟 2 — 從來源文件中提取文字

運行提取腳本，傳遞輸入路徑：

SCRIPT_PATH=""
for candidate in \
  "$HOME/.copilot/skills/book-to-skill/scripts/extract.py" \
  "$HOME/.agents/skills/book-to-skill/scripts/extract.py" \
  "$HOME/.claude/skills/book-to-skill/scripts/extract.py" \
  ".github/skills/book-to-skill/scripts/extract.py" \
  ".claude/skills/book-to-skill/scripts/extract.py" \
  ".agents/skills/book-to-skill/scripts/extract.py" \
  "$HOME/.config/agents/skills/book-to-skill/scripts/extract.py" \
  "$HOME/.config/amp/skills/book-to-skill/scripts/extract.py"
do
  if [ -f "$candidate" ]; then
    SCRIPT_PATH="$candidate"
    break
  fi
done

if [ -z "$SCRIPT_PATH" ]; then
  echo "找不到 book-to-skill 的 scripts/extract.py" >&2
  exit 1
fi

PYTHON_BIN="${PYTHON_BIN:-python3}"
if ! command -v "$PYTHON_BIN" >/dev/null 2>&1; then
  PYTHON_BIN="python"
fi

"$PYTHON_BIN" "$SCRIPT_PATH" $INPUT_PATHS --mode <BOOK_TYPE> --install-missing ask

在提取之前，腳本會檢查偵測到的格式所需的可選 Python 套件。如果缺少更好的提取器，它會提示使用者可用的備用方案。非互動式工作階段預設使用備用方案，除非安裝模式明確設定為 yes。

提示 — 預先檢查環境： 運行 "$PYTHON_BIN" "$SCRIPT_PATH" --check 以列印每個格式的報告，說明安裝了哪些提取器以及安裝缺少的套件的確切命令，而不處理任何檔案。當使用者報告設定或品質問題時很有用。

這會建立：

<tempdir>/book_skill_work/full_text.txt — 所有來源的合併提取文字，並帶有清晰的視覺分界線。
<tempdir>/book_skill_work/metadata.json — 整體合併大小、字數、頁面、token 計數，以及已處理的個別 sources 的詳細列表。

讀取 <tempdir>/book_skill_work/metadata.json 以檢查結果。

步驟 2.5 — 預先成本估算

讀取 <tempdir>/book_skill_work/metadata.json 並在進行任何生成之前向使用者顯示估算：

📖 偵測到的來源：<total_sources> 個來源
<從來源元數據列表中列出每個來源的檔案名稱和格式>
📄 合計頁數/章節：~<N> | 字數：~<N> | 總 token 數：~<N>K

💰 估計 token 成本（完整轉換/更新）：
   輸入（讀取 + 提示）：~<N>K tokens
   輸出（生成的/更新的技能檔案）：~<N>K tokens
   總計：                           ~<N>K tokens

   成本：將上述 token 計數乘以您模型目前的
   輸入/輸出每 1M token 的費率（價格和模型名稱經常變化 —
   不要硬編碼它們；引用今天的費率並將其標記為估算）。

   ⏱  預計時間：~<N> 分鐘

📁 將要生成/更新的檔案：
   SKILL.md + 章節檔案 + 詞彙表 + 模式 + 備忘錄

➡  是否繼續完整轉換/更新？（或輸入 "analyze only" 以先預覽）

如何估算：

輸入 tokens ≈ estimated_tokens 來自 metadata × 1.3（每次章節傳遞的提示開銷）
輸出 tokens ≈ 章節數 × 每章節預算 + 4,000（SKILL.md）+ 4,500（詞彙表 + 模式 + 備忘錄）
- 根據 BOOK_TYPE 的每章節預算中點（深度在步驟 4 中決定，並可能提高它）：text ≈ 1,000，technical ≈ 1,800。如果使用者已經指示僅參考 vs 深入研究，請使用步驟 7 矩陣的對應行。
成本：報告 token 計數並乘以使用者當前的每 1M token 輸入/輸出費率。不要硬編碼美元金額 — 模型名稱和價格會變化；如果你顯示一個，請將其標記為估算並註明日期。

等待使用者在繼續之前確認。如果他們說 "analyze only"，請切換到模式 2。

步驟 2.6 — 大型書籍（> 50k tokens）的 REPL 風格存取

受遞迴語言模型（RLM）範例啟發：將 full_text.txt 視為可查詢的語料庫，而不是一次性讀取。將整個檔案載入到上下文中會消耗您後來生成所需的預算。

對於超過約 50k tokens 的書籍，優先使用程式化探測而不是無限制的 Read(full_text.txt)：

# 在任何 Read 之前檢查大小
wc -w "$FULL_TEXT_PATH"

# 在不載入整個檔案的情況下尋找章節偏移量
grep -n -E "^\s*(Chapter|CHAPTER)\s+[0-9]+" "$FULL_TEXT_PATH" | head -40

# 只提取您需要的章節（行號 start..end 包含）
sed -n '<start>,<end>p' "$FULL_TEXT_PATH"

# 在聲明之前驗證框架是否確實被提及
grep -c -i "westrum\|dora" "$FULL_TEXT_PATH"

# 具有偏移量/限制的目標 Read 避免了傾倒整個檔案
# Read(file_path=full_text.txt, offset=<line>, limit=<lines>)

在步驟 3（結構分析）、步驟 7（每章節摘要）和步驟 8（詞彙表 / 模式提取）中使用此方法。對於低於 50k tokens 的書籍，單次 Read 即可。

為什麼這很重要：一本 200 頁的書籍約為 75k tokens。每章節重讀一次（28 次傳遞）花費約 2M 輸入 tokens；使用 grep + sed 只提取相關片段可使生成成本與輸出成正比，而不是與來源成正比。

步驟 3 — 分析書籍結構

讀取提取的 full_text.txt 的前 8,000 個字元，以識別：

書籍標題和作者
章節結構（尋找「Chapter N」、「PART I」、編號標題、目錄）
核心主題和主題領域
大約的章節數量

然後，如果有的話，讀取目錄部分以映射所有章節。

如果模式是「僅分析」： 現在產生提取報告並停止。結構：

## 提取報告 — <標題>

### 作者的核心框架
- **<框架名稱>**：<它是什麼以及何時應用>

### 關鍵原則
- <原則>：<可操作的規則>

### 技術與方法
- <技術>：<逐步操作或操作方法>

### 反模式
- <應避免的事項>：<原因>

### 建議的技能名稱
`{作者姓氏}-{核心概念}` — 例如 `cialdini-influence`

### 偵測到的章節
| # | 標題 | 主要框架 |

步驟 4 — 詢問目的（僅限完整轉換）

在生成之前，詢問使用者：

"這個技能應該幫助您做什麼？（選擇一個或多個）

在工作中應用作者的框架

用作者的心理模型思考

參考特定章節和概念

以上皆是"

使用答案來權重 SKILL.md 核心部分中要突出的內容。

從答案推導 DEPTH（無需額外提示）：

答案僅為選項 3（參考）→ DEPTH=reference — 精簡、快速查詢的章節。
答案包含選項 1、2 或 4 → DEPTH=study — 更深入的章節，包含更多詳細工作、範例和推理。

DEPTH 和 BOOK_TYPE 共同設定步驟 7 中的每章節 token 預算。不要問單獨的「研究 vs 參考」問題——它在此處被推導出來。（在模式 2/3 中，跳過步驟 4，預設 DEPTH=study。）

步驟 5 — 確定技能名稱

如果提供了 SKILL_NAME，則將其用作技能 slug。否則，提出兩個選項並讓使用者選擇：

按作者-概念：{作者姓氏}-{核心概念}（例如 cialdini-influence, meadows-systems）
按標題：從書籍標題轉換為小寫連字符（例如 designing-data-intensive-apps）

如果書籍具有強烈的方法論身份，則預設使用作者-概念格式。

選擇目標技能根目錄（SKILLS_HOME）。探測使用者的檔案系統以尋找現有的技能家目錄，並根據使用者正在運行的主機來選擇：

主機代理	個人技能路徑

Leutenegger/book-to-skill

book-to-skill 是什麼？

在你喜歡的 AI 中提問

說明文件

書籍轉技能轉換器

哲學

操作模式

1. 完整轉換（預設）

2. 僅分析

3. 從先前的分析生成

4. 更新 / 合併（現有技能）

技能位置

步驟 0 — 範圍外檢查

步驟 1 — 驗證輸入

步驟 1.5 — 識別內容類型

步驟 2 — 從來源文件中提取文字

步驟 2.5 — 預先成本估算

步驟 2.6 — 大型書籍（> 50k tokens）的 REPL 風格存取

步驟 3 — 分析書籍結構

步驟 4 — 詢問目的（僅限完整轉換）

步驟 5 — 確定技能名稱

相關技能

steipete/notion

langchain-ai/langchain

bytedance/podcast-generation

composiohq/twitter-algorithm-optimizer

composiohq/competitive-ads-extractor

upstash/context7