技術書を1冊買って読み終えて、3ヶ月後に「7章に何が書いてあったか」を思い出せない経験は多くのエンジニアにある。PDFを全文検索しても返ってくるのはページ番号の羅列で、答えではない。Claudeに本の内容を尋ねればハルシネーションするか「学習データに含まれていない」と返される。

book-to-skill（virgiliojr94/book-to-skill）はこの非対称性を埋めるOSSで、PDFまたはEPUBの技術書をClaude Codeのスキルに変換し、/<book-slug> replicationのような呼び出しで該当チャプターだけがオンデマンドで読み込まれる仕組みを提供する。本記事ではREADMEに記載された機能と内部設計を整理し、RAGとの差分・抽出パイプラインのトレードオフ・実際の使い方までを解説する。Claude Code全体の使い方はClaude Code完全ガイド2026：インストールから本番運用までを参照してほしい。

3行でわかるbook-to-skill

  • PDF/EPUBを入力に、コアモデル＋チャプター別MD＋用語集＋パターン集＋チートシートからなるClaude Codeスキル一式を ~/.claude/skills/<slug>/ に書き出すツール
  • コンパイル時に一度だけ著者のフレームワークを抽出して命名するため、RAGの「クエリごとのチャンク類似検索」と違い、章をまたいだ再利用可能な構造として扱える
  • 技術書はDocling、テキスト中心の本はpdftotextに振り分ける2モード設計。Step 1.5で本の種類を尋ね、適切な抽出パスを選ぶ

book-to-skillとは何か——1冊を1個のスキルへ圧縮するツール

book-to-skillはPython製のClaude Codeスキルで、ローカルのPDFまたはEPUBを引数に渡すと、その本に特化した別のスキルを~/.claude/skills/配下に新規作成するメタスキルだ。GitHub公開からの数日でスター144・フォーク19を集めており、READMEはMITライセンスで提供されている。

入力となる書式は2系統で、PDFとEPUBの両方をサポートする。PDFは本の中身に応じて2モードに分岐する。

入力 推奨ツール インストール 速度の目安
散文中心のPDF pdftotext（poppler） sudo apt install poppler-utils 即時
散文中心のフォールバック1 PyPDF2 pip3 install PyPDF2 即時
散文中心のフォールバック2 pdfminer.six pip3 install pdfminer.six 即時
技術書（コード・表・数式） docling pip3 install docling 約1.5秒/ページ
EPUB（推奨） ebooklib + beautifulsoup4 pip3 install ebooklib beautifulsoup4 即時
EPUB（フォールバック） 標準ライブラリzipfile 追加インストール不要 即時

Step 1.5に「本は技術寄りか散文寄りか」を尋ねるインタラクションが組み込まれており、回答に応じてscripts/extract.py --mode <technical\|text>が呼び分けられる。Doclingはテーブルやコードブロックを失わずMarkdownに抽出できる代わりに、103ページの本で約164秒かかる。pdftotextは同じ本を0.1秒で処理するが、テーブルとコードブロックは失われる。

この章のポイント

  • PDFとEPUB両対応。最低1つの抽出ツールがインストール済みであれば動く
  • 本の種類で2モードに分岐し、技術書はDocling・散文はpdftotext系で抽出
  • Doclingはコード・表を保つが約1.5秒/ページ、pdftotextは即時だが構造を失う

なぜRAGではなく「スキル化」なのか——コンパイル時抽出の設計思想

book-to-skillの面白さは、RAG（Retrieval-Augmented Generation）と問題設定が違う点にある。READMEのFAQが両者の違いを明確に言語化している。

RAGはクエリ時に動く。チャンク化→埋め込み→類似ベクトル検索→プロンプト注入。「Xに関する箇所を見つけて」に最適化されている。
book-to-skillはコンパイル時に動く。1度の深い解析で著者の実際のフレームワークを抽出し、命名し、いつ使うかを書き、アンチパターンを捕捉する。出力は著者が何年もかけて構築した構造そのもので、文章間の類似検索ではない。

RAGは「あなたのクエリに近い文を返す」のに対し、スキル化は「著者が組み立てた12個のフレームワーク」を整理して再利用可能な形に落とす。50冊以上の横断検索ではRAGが勝ち、1冊を深掘りしてその枠組みを自分の作業に常駐させるならスキルが勝つ、と公式は明確に立場を表明している。

このアプローチは新しいものではなく、Anthropicの推奨するスキル＝フォルダの設計思想を継承している。Claudeのスキル機能の仕組みについてはClaude Skillsを徹底解説｜スキルはフォルダ——Anthropicエンジニアが明かした仕組みと使い方で詳しく整理しているが、ポイントはSKILL.mdに前置きとなるメンタルモデル（約4,000トークン）を置き、章ごとのMarkdownをオンデマンドでロードする多層構成にある点だ。

書籍を全部コンテキストに突っ込むと、400ページの本は約20万トークンに達し、毎回の会話冒頭で予算を食い潰す。スキル化すれば必要な章だけをロードでき、しかもメンタルモデルは常に最初の数千トークンに前置きされる——これがbook-to-skillが「単なるPDFダンプ」と決定的に違うところだ。

アーキテクチャ：抽出からスキル書き出しまでの3レイヤ

book-to-skillの内部処理は、READMEの「How it works」セクションが整理しているとおり、抽出 → 解析 → スキル生成の3レイヤで動く。各レイヤは独立しており、抽出器の選定だけ人間に確認するインタラクション設計になっている。

flowchart TB Input["入力 book.pdf or book.epub"] Q["Step 1.5 本は技術寄りか散文寄りか"] subgraph Extract ["Layer 1 抽出"] ExtPdfT["technical docling
Markdown table と code を保持"] ExtPdfP["text pdftotext
PyPDF2 pdfminer の順にフォールバック"] ExtEpub["EPUB ebooklib
zipfile にフォールバック"] end Tmp["中間ファイル
full_text.txt と metadata.json"] subgraph Analyze ["Layer 2 Claudeが構造解析"] A1["title と author の抽出"] A2["目次と章構造の検出"] A3["章ごとの要約 800-1200 トークン"] A4["technical では Code と Table 節を保持"] A5["glossary patterns cheatsheet 生成"] A6["SKILL.md にコアメンタルモデル"] end Out["スキル本体
SKILL.md + chapters + glossary.md
+ patterns.md + cheatsheet.md"] Cleanup["中間ファイルを削除"] Input --> Q Q -->|technical| ExtPdfT Q -->|text| ExtPdfP Input -->|EPUB| ExtEpub ExtPdfT --> Tmp ExtPdfP --> Tmp ExtEpub --> Tmp Tmp --> Analyze --> Out Out --> Cleanup style Q fill:#fff3cd style Extract fill:#d4edda style Analyze fill:#cce5ff style Out fill:#f8d7da

Layer 1：抽出器の選定

抽出はscripts/extract.pyに集約されている。PDFは--mode引数で技術書/散文を切り替え、EPUBはebooklibを優先しつつzipfileにフォールバックする。インストールされているツールを順番に試し、見つからなければ「次のコマンドを実行してください」と表示するため、初回ユーザーが詰まらないようになっている。

抽出結果はランダムに作る話ではなく、必ず/tmp/book_skill_work/full_text.txtとmetadata.jsonに書き出される。Claude本体はこの中間ファイルだけを読む——この分離が、ローカルの抽出ツールとLLMの責務を切り分けるポイントになっている。

Layer 2：Claudeによる構造解析

中間ファイルを受け取ったClaudeは、まずタイトル・著者・目次を確定する。次に章ごとに800〜1,200トークンの要約を生成する。技術書モードであれば、章要約にCode Examples節とReference Tables節が追加され、抽出時にDoclingが保った表とコードブロックがそのまま埋め込まれる。

その上で書籍全体を横断する補助ファイルを3つ作る。

  • glossary.md——重要用語をアルファベット順に整理し、章番号への参照付き
  • patterns.md——アルゴリズム・テクニック・デザインパターンの一覧
  • cheatsheet.md——意思決定表とクイックリファレンス

最後にSKILL.mdにコアメンタルモデルとチャプターインデックスを書き、~/.claude/skills/<slug>/へ配置する。Layer 1の中間ファイルは削除される——ローカルに余計なテキストファイルを残さない設計だ。

Layer 3：オンデマンド読み込み

生成後、/<your-book-slug> replicationのようにスキルを呼び出すと、ClaudeはSKILL.mdを読んでチャプターインデックスを参照し、トピックに該当するチャプターMDだけを追加でロードする。章ファイルはスキル予算には常駐しない——これが「200Kの本でも会話あたりトークン消費が一定」を成立させる肝だ。

インストールと依存関係：3コマンドで導入できる

READMEの推奨インストール手順は2系統あり、どちらも数コマンドで終わる。Claude Codeのセッション内に1行貼り付ける方法と、curlで直接配置する方法だ。

# Claude Codeセッション内で実行
Install book-to-skill: https://raw.githubusercontent.com/virgiliojr94/book-to-skill/master/SKILL.md

手動セットアップする場合は次のコマンドでSKILL.mdと抽出スクリプトを配置する。

mkdir -p ~/.claude/skills/book-to-skill/scripts

curl -o ~/.claude/skills/book-to-skill/SKILL.md \
  https://raw.githubusercontent.com/virgiliojr94/book-to-skill/master/SKILL.md

curl -o ~/.claude/skills/book-to-skill/scripts/extract.py \
  https://raw.githubusercontent.com/virgiliojr94/book-to-skill/master/scripts/extract.py

Pythonの依存はオプションで、扱いたい本の形式に応じて入れる。技術書を主に扱うならDoclingだけは入れておく価値が大きい。Doclingがないと、技術書の表とコードブロックがすべて散文として吐き出され、抽出後のClaude解析もそのテキストを再構造化しないといけなくなり、品質が大きく落ちる。

# 散文中心の本だけで十分なら（最小構成）
sudo apt install poppler-utils

# 技術書も扱うなら（推奨）
pip3 install docling

# EPUBも扱うなら
pip3 install ebooklib beautifulsoup4

# 全部入り
sudo apt install poppler-utils && \
  pip3 install docling PyPDF2 pdfminer.six ebooklib beautifulsoup4

抽出スクリプトは「インストール済みのツールを順番に試す」設計なので、すべて入れておけば本ごとに最適な経路が選ばれる。

使い方：PDFまたはEPUBを引数に渡すだけ

スキルを呼び出す書式は/book-to-skill <path-to-pdf-or-epub> [skill-name-slug]で、第2引数のスラッグは省略するとファイル名から自動生成される。

# PDFを渡し、ファイル名からスラッグを自動生成
/book-to-skill ~/Downloads/designing-data-intensive-applications.pdf

# EPUBにカスタムスラッグを指定
/book-to-skill ~/books/clean-code.epub clean-code

# 絶対パス＋明示的なスラッグ
/book-to-skill /tmp/ddd-evans.pdf domain-driven-design

スキル生成後は他のClaude Codeスキルと同じ呼び出し方をする。

# コアメンタルモデルだけロード
/designing-data-intensive-apps

# トピックを指定して該当章を探索
/designing-data-intensive-apps replication

# 章番号で直接ジャンプ
/designing-data-intensive-apps ch05

# 自然言語で「どんな章があるか」を問う
/designing-data-intensive-apps "what chapters do you have?"

replicationのように単語を渡すと、ClaudeはSKILL.mdのチャプターインデックスを参照し、レプリケーションを扱う章のMarkdownを優先的に開く。ハルシネーションを減らすためにも、章本文に直接当たるこの動作は重要だ。

スキル化の応用としては、自分の業務固有の手順をMarkdownにまとめてスキルにする方向もある。意思決定をワークフローに落とすパターンはClaudeで実践するプリモーテム｜意思決定前に失敗を予見するスキル設計で具体例とともに整理しているので、書籍化以外のスキル設計にも応用したい場合に併読してほしい。

生成されるスキルの構造：SKILL.md／chapters／3つの補助MD

~/.claude/skills/<slug>/に書き出されるファイル構成と各ファイルの役割をREADMEから引用すると次のとおりだ。

ファイル 役割 サイズ目安 読み込みタイミング
SKILL.md 著者の核となるメンタルモデル＋章インデックス 約4,000トークン スキル起動時に常駐
chapters/ch01-*.md … 章ごとの要約。技術書はCode + Tables節を含む 各約1,000トークン トピック該当時のみ
glossary.md 用語集（アルファベット順、章参照付き） 約1,500トークン 用語問い合わせ時のみ
patterns.md テクニック・アルゴリズム・デザインパターン 約2,000トークン パターン問い合わせ時のみ
cheatsheet.md 意思決定表とクイックリファレンス 約1,000トークン クイック参照時のみ

合計で常駐するのはおおよそ4,000トークン分だけで、章を読みに行くたびに+1,000トークン程度ずつ増える。400ページの本（約200,000トークン）を毎回コンテキストに乗せる場合と比べ、典型的な質問では実質読み込み量を1〜3%程度に抑えられる計算になる。

検証環境注記: 上記は公式README記載のサイズ見積もり（約4,000・約1,000など）からの試算であり、章サイズは原書の章長に依存する。極端に長い章を含む本では章MDが2,000〜3,000トークンに膨らむ可能性もある。

ベンチマーク：pdftotext vs Docling

READMEには103ページの技術書を対象としたCPU実測値が掲載されている。両者を「同じテキスト」を抽出するわけではなく、コードブロックとテーブルが結果に含まれるか否かが一番大きな差だ。

抽出方式 所要時間 テキストトークン テーブル数 コードブロック数
pdftotext 0.1秒 27K 0 0
Docling 164秒 27K（+1.2%） 48 36

トークン量はほぼ同じだが、Doclingは48個のテーブルと36個のコードブロックをMarkdown構造として保持している。テーブルが散文化されるとClaude側で再構造化のコストがかかり、章要約に貼られるサンプルコードもインデントが崩れる。

「3分待って構造を保つ」か「即時だが平文化するか」は、本の性質で決めるべきだ。アルゴリズム書・SQL書・型システム書などテーブルとコードが意味の核を持つ書籍はDocling一択でよい。プロジェクト経営書・哲学書・歴史書など散文だけが意味を持つ書籍はpdftotextが適している。

競合との位置づけ：NotebookLM／生PDFダンプ／RAGとの違い

book-to-skillと近いユースケースを持つ競合との違いを表で整理する。

観点 book-to-skill 生PDFをコンテキストに貼る RAG（ベクトルDB） NotebookLM
想定タスク 1冊を深堀りして常用 1回の質問に応える 多くの本を横断検索 多くの本を横断検索
読み込みタイミング コンパイル時1回 毎クエリ 毎クエリ（埋め込み） 毎クエリ（Google側）
1質問あたりトークン 約4,000＋関連章 全文（〜200K） チャンク数本 UIで完結
章ナビゲーション あり（チャプターインデックス） 全文検索のみ チャンク類似 全文検索＋音声
著者フレームワークの命名 あり（patterns.md） なし なし なし
ハルシネーション抑制 章MDを根拠にする コンテキストに依存 チャンク次第 比較的低い
自分のCLI/IDEに常駐 できる（Claude Code skill） できない できる できない（ブラウザ）
価格 OSS無料 API代のみ DB＋埋め込みコスト Googleアカウント
主な弱点 1冊単位、横断は不向き 高コスト・遅い 検索精度依存 専用タブが要る

NotebookLMはGoogleの強力なツールで、80冊以上の図書館的な横断検索や音声生成（Audio Overview）が要件にあるならそちらが向く。一方、「1冊を深く・コーディングと並行して」という軸だと、ブラウザを開かずに済むbook-to-skillが優位になる場面が多い。

別の方向の比較として、Reddit・X・YouTubeを横断するリサーチに特化したスキルがlast30days-skill完全ガイド｜Reddit・X・YouTube横断AIリサーチスキルの使い方2026年版にある。スキルのオンデマンド読み込み設計は同じ系譜なので、book-to-skillの動きを別の用途で見たい人の入り口になる。

使う上での注意点：誤抽出・OCR・ライセンスの3つ

実運用で詰まりやすいポイントを3つ整理しておく。

1. スキャンPDFは抽出できない。 book-to-skillが想定するのは「テキスト埋め込み済みのPDF」だ。書籍の自炊スキャンや古いPDFはOCRで先に文字化する必要がある。Docling・pdftotext・PyPDF2のいずれもOCR機能は持たないため、tesseractやocrmypdfで前処理してから渡す方針になる。READMEではOCRに関する明示的なサポート記述はない（2026-05-06時点）。

2. 図版は抽出されない。 抽出はテキストとテーブルとコードに限られ、図解やシーケンス図はスキルに含まれない。アーキテクチャ書のように「図がコンテンツの半分」の書籍は、別途自分でMermaidやテキスト記述に置き換えてSKILL.mdに追記する運用が向いている。

3. ライセンスは自分で確認する必要がある。 book-to-skill自体はMITだが、入力となる書籍は当然著作権下にある。生成したスキルを社外に再配布したり公開リポジトリに置くのは多くの場合NGで、~/.claude/skills/<slug>/は個人の作業環境内に留めるのが安全だ。チームで共有したい書籍があるなら、出版社のライセンス条件を先に確認する必要がある。

# スキャンPDFの前処理例：ocrmypdfで埋め込みテキスト化
ocrmypdf input-scanned.pdf input-with-text.pdf

# 抽出が想定外の場合、まず中間ファイルを確認
ls /tmp/book_skill_work/
cat /tmp/book_skill_work/metadata.json
head -100 /tmp/book_skill_work/full_text.txt

中間ファイルは削除されるが、削除前に処理が止まった場合はここを覗くと「Doclingが何を抽出したか」「章境界の検出はどうなったか」が分かる。Layer 2の解析品質はLayer 1の出力次第なので、品質に違和感がある場合はまず中間ファイルを見るのが診断の起点になる。

どんなチームに向くか——「同じ本を全員が共通の枠組みとして使う」場面

book-to-skillが効くのは、書籍がチームの共通言語になる種類のチームだ。代表的なケースを挙げる。

  • アーキテクチャ判断を毎週する開発チーム ——『Designing Data-Intensive Applications』をスキル化しておけば、レプリケーション・パーティショニング・コンセンサスといった用語が会話に出るたびに、その章の要点が自動で参照できる
  • DDDを採用しているチーム ——『Domain-Driven Design』のbounded context・aggregate・anti-corruption layerなど、原典の用語を平等に再生産するため、新メンバーが入ったときの認識揃えが速い
  • コードレビュー文化を醸成中のチーム ——『Clean Code』『The Pragmatic Programmer』をスキル化し、レビューコメントの根拠として参照できる
  • 規格・仕様書を多用するチーム ——HTTP/2のRFC、SQL標準、特定言語の言語仕様PDFなど、章番号で議論する文書を持つ

逆に、社内文書を全部スキル化したい・80冊のライブラリを横断検索したいケースには向かない。前者は社内Wiki＋RAG、後者はNotebookLM側の領域だ。book-to-skillは「1冊を作品として扱う」機能特化のツールと捉えるとしっくりくる。

まとめ：技術書を「読み返す」から「作業に常駐させる」へ

book-to-skillが提示しているのは、書籍との付き合い方の構造的な転換だ。読み終わった本を本棚に戻す代わりに、その本のフレームワーク部分だけをClaude Codeに常駐させ、コーディング・設計判断・レビューの最中にいつでも呼び出せる状態にする。

RAGがしているのは類似検索で、本を「探す対象」として扱う。book-to-skillがしているのは構造抽出で、本を「再利用可能なフレームワーク集」として扱う。前者がGoogle検索なら、後者は著者を傍に置くイメージに近い。どちらが必要かはタスクで決まる。

導入も軽い。pip3 install doclingとInstall book-to-skill: ...の2行で動く環境ができる。気になる本があるなら、まず最初の1冊を試して、~/.claude/skills/<slug>/に何が書き出されるかを確認するのが理解の最短経路だ。Claude Codeのスキル設計を体系的に踏まえた上で運用したい場合は、本記事冒頭で示したClaude Code完全ガイドと、Anthropic公式ドキュメントを併読してほしい。

参照ソース