book-to-skill——技術書PDFを、エージェントが使う『スキル』に変える

ふむふむ。いい技術書を買って、一度は読んだ。なのに三か月後、「第7章って何だったっけ？」になる——ありません？

チカちゃん的には、これかなりあるあるです。PDFを開いてもページ一覧しか出ない。エージェントに聞くと、学習データのぼんやりした記憶で答えてくる。自分でノートを取ると、200行のメモができて二度と開かない。

そこに、GitHubの週次トレンドで勢いよく上がってきたのが book-to-skill（virgiliojr94/book-to-skill）です。ひと言でいうと、手元の本やドキュメントを、コーディングエージェントがオンデマンドで読めるスキルに変換する道具。執筆時点でGitHubスターは約17,600。ライセンスはMIT。対応ホストは Claude Code / GitHub Copilot CLI / Amp など、Agent Skills 標準を読むクライアントです。

「要約ツール」じゃありません。公式が繰り返しているのはここ——structure, not a summary。著者の枠組み・判断ルール・アンチパターンを、スキルとして使える形に蒸留する。今日はその入れ方から、最初の1冊の変換、ハマりどころまで歩いてみます。

本記事は公開情報をもとにした個人的な技術メモです。第三者ツール・AIサービス・モデルの仕様、料金、利用条件、安全性は変わる可能性があります。導入前に公式ドキュメント、ライセンス、利用規約、商用利用条件、データ送信先を確認してください。業務環境や秘密情報を含む環境では、隔離環境で検証してから利用することをおすすめします。著作権のある書籍を処理する場合は、自分で正当に所持しているコピーに限り、生成スキルの再配布は避けてください。

book-to-skill は何をするのか——30秒でつかむ

流れは3ステップです。

1. 指す —— /book-to-skill ./my-book.pdf（またはフォルダ、glob、複数ファイル）
2. 蒸留する —— 抽出スクリプトがテキスト化し、エージェントが章構成・フレームワーク・用語を整理してスキルを書く
3. 使う —— /my-book replication のように聞くと、必要な章ファイルだけ読んで答える

生成されるのはだいたいこんな構成です（公式READMEの目安トークン量）。

ファイル	役割	だいたいのサイズ
SKILL.md	中核のメンタルモデル＋章インデックス	約4,000トークン
chapters/ch01-*.md …	章ごとの要約（必要なときだけ読む）	各約1,000トークン
glossary.md	用語集（章参照つき）	約1,500トークン
patterns.md	技法・アルゴリズム・パターン	約2,000トークン
cheatsheet.md	判断表・クイックリファレンス	約1,000トークン

ポイントは 章ファイルはオンデマンド なこと。毎回本全体をコンテキストに流し込まない。公式の実測では、1問に答えるときのコンテキスト投入量が「本まるごとdump」より 24×〜51×少ない（Think Python 2 / Working Backwards / AI Engineering での測定。手法は docs/PERFORMANCE.md）。

チカちゃん的には、ここが面白い。大きなコンテキスト窓は「全部載せることを可能にする」だけで、「全部載せることが賢い」わけじゃない、という話なんですよね。

PDF dump / RAG / NotebookLM と何が違うの？

ここ、いちばん誤解しやすいので一度並べます。

やり方	いつコストを払うか	何が返るか	向きやすい仕事
コンテキストにPDFを貼る	会話の毎ターン	生テキストの再解釈	二度と使わない一回限りの読み
RAG	クエリ時に検索	類似チャンク	本棚全体から「Xに触れた箇所」
NotebookLM 等	ノートブック側	横断Q&A	多数の本を横断検索
book-to-skill	変換時に一度	名前付きフレームワーク・判断ルール	1冊（または密な束）を仕事中に適用

公式FAQの言い方がうまいです。RAGは 「クエリに近いチャンクはここ」。スキルは 「この著者が何年もかけて作った枠組みが、使える形でここ」。

広い棚を索引化するならRAG。一本の背表紙をマスターして、コーディング中に手を伸ばすなら book-to-skill。補完関係であって、どっちが勝つ試合でもない。

事前確認——動かす前に知っておきたいこと

• 必要なもの: 対応エージェント（Claude Code / Copilot CLI / Amp など）と、ローカルで動く Python 3
• 入力形式: PDF, EPUB, DOCX, TXT, Markdown, reStructuredText, AsciiDoc, HTML, RTF, MOBI/AZW/AZW3（後者はCalibreの ebook-convert が必要）
• 二系統のインストールを混同しない（公式INSTALLが強調）:
  • エージェントスキル → git clone を skills フォルダへ。/book-to-skill が使える本丸
  • スタンドアロンCLI → pip install book-to-skill。抽出エンジンだけ。スラッシュコマンドは登録されない
• データ: 抽出はローカル。ただしクラウドLLMのエージェントなら、生成フェーズでテキストはプロバイダのデータ条件に従う（普通のプロンプトと同じ）
• 著作権: ツール本体は書籍を同梱しない。自分が正当に持つコピーを処理する前提。第三者著作物の生成スキルを公開・配布するのは避け、個人利用メモとして扱う

インストール——ホスト別に置く場所を決める

Claude Code（いちばんよく見る経路）

git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill

セッション内で次のように依頼するだけでも可、と公式は書いています。

Install book-to-skill: https://raw.githubusercontent.com/virgiliojr94/book-to-skill/master/SKILL.md

ただし公式INSTALLは、モジュラーな抽出エンジン一式を確実に取るなら git clone 推奨と明記しています。チカちゃん的にも、ここは clone 一択でいいと思います。

GitHub Copilot CLI

git clone https://github.com/virgiliojr94/book-to-skill.git ~/.copilot/skills/book-to-skill
# セッション内で:
/skills reload
/skills info book-to-skill

クロスエージェント（Copilot と Amp の両方が見る場所）

git clone https://github.com/virgiliojr94/book-to-skill.git ~/.agents/skills/book-to-skill

抽出の健全性チェック（おすすめ）

clone したあと、依存が足りているか一発で確認できます。

python3 ~/.claude/skills/book-to-skill/scripts/extract.py --check
# パスはホストに合わせて ~/.copilot/... や ~/.agents/... に読み替え

足りない抽出器があれば、入れるコマンドまで表示してくれます。ここを飛ばすと、技術書なのに構造が全部潰れたテキストで進んでしまう——地味に痛い罠です。

スタンドアロンCLI（任意）

pip install "book-to-skill[pdf,epub,docx]"
book-to-skill --check
book-to-skill ~/path/to/book.pdf --mode text

繰り返しますが、これは 抽出だけ。エージェントの /book-to-skill フロー（分析→スキル生成）まではやりません。

最初の1冊——変換フローを手で追う

ここでは Claude Code 想定で書きます。置き場所は上の表に合わせて読み替えてください。

1. 変換コマンドを投げる

/book-to-skill ~/Downloads/your-book.pdf
# スキル名を自分で決めるなら:
/book-to-skill ~/Downloads/your-book.pdf my-book-slug

フォルダや複数ソースも公式に対応しています。

# docs フォルダごと1スキルに
/book-to-skill ~/workspace/project-docs/ project-knowledge

# 論文とメモを束ねる
/book-to-skill ~/papers/a.pdf ~/notes/export.txt unified-research

# 既存スキルに新しい資料を fold-in
/book-to-skill ~/articles/new-paper.pdf ~/.claude/skills/project-knowledge

2. 「技術寄り or 文章寄り？」に答える

抽出の前に、本の種類を聞かれます。

選択	向き	主な抽出器	速度感
Technical	コード・表・数式が多い	Docling	おおよそ1.5秒/ページ
Text-heavy	散文中心	pdftotext → pypdf → pdfminer	ほぼ即時
Not sure	迷ったとき	速い方（text）	品質が足りなければ警告

公式の103ページ技術PDF比較では、pdftotext が0.1秒で表0・コード0、Docling が164秒で表48・コードブロック36、という実測があります。プログラミング本なら technical。ビジネス書の散文なら text。ここを間違えると「速いけど中身が平ら」になりがち。

3. コスト見積もりを見てから進む

抽出後、生成に入る前にトークン見積もりが出ます。ここで一度止まれるのが親切設計。

公式のワンパス変換コスト目安（Claude Sonnet 4.5 を $3 / $15 per MTok と置いた推定。モデル名と単価は変わるので、その日の料金で掛け直すこと）:

本	入力	出力	おおよそ
Think Python 2（244ページ）	155K	28K	約 $0.88
Working Backwards（371ページ）	228K	19K	約 $0.96
Pro Git（501ページ）	298K	23K	約 $1.23

ざっくり 1冊あたり約1ドル前後を一度払うイメージ。その代わり、毎回PDFを全文投入するコストを毎回払わなくてよくなる——公式の「amortization（償却）」の話です。

不安なら、ここで analyze only にして分析レポートだけ見るモードもあります。

4. できあがったスキルを使う

/designing-data-intensive-apps                  # 中核の枠組みを読む
/designing-data-intensive-apps replication      # トピックで章を探す
/designing-data-intensive-apps ch05             # 第5章に潜る
/designing-data-intensive-apps "what chapters do you have?"

Copilot CLI では生成直後に /skills reload が必要なことがあります。Claude Code / Amp は次セッションで拾う、と公式USAGEにあります。

本以外に何を入れると効くか

名前は book ですが、入力は「構造のある散文」全般です。公式が挙げている候補:

• 社内ドキュメント —— ADR、runbook、オンボーディング資料。docs/ を1スキルにまとめて実装中に聞く
• ブランド／デザインシステム —— トーンガイド、コンポーネント原則
• 研究クラスタ —— 論文束＋自分のメモ。あとから fold-in で更新
• 仕様・標準 —— RFC、API契約、コンプライアンス文書

チカちゃん的な判定基準はシンプルで、「何度も開き直して、頭に入ってたら楽なのに……と思う文書」かどうか。一回読んで捨てる資料をスキル化する必要は薄いです。

注意点——すごい、のあとに置くブレーキ

1. スキャンPDFは別問題

デジタルPDF向け。画像スキャン中心のPDFは、先にOCRが必要です。ここを飛ばすと、抽出が空に近いのに生成だけ走って悲しいことになります。

2. 章見出しが特殊だと自動分割が弱い

公式PERFORMANCEの注記どおり、Pro Git のように Chapter N 見出しがなくセクションタイトルだけの本は、自動章分割が効かないことがあります。変換自体は動くけれど、章ファイルの切り方が荒くなる。そのときは手動でセクションを指定する前提で。

3. 生成コストと時間は「一度きり」でも無視できない

長い技術書の technical モードは、Doclingだけで数分〜十数分、そのあとエージェントが章ごとに書く時間も乗ります。バックグラウンドで流す前提のほうが精神衛生がいい。

4. 出力は「要約された二次資料」であって原典の代替ではない

Quality Rule にも「生テキストをコピーしない」「合成・要約・シグナル抽出」とあります。引用が厳密に必要な場面では、必ず原典に戻る。スキルは思考の道具であって、書誌的な証拠庫じゃない。

5. 生成スキルの再配布は危険

著作権のある第三者書籍から作ったスキルを公開・共有すると、権利者の権利を侵害し得ます。個人利用に留める。社内docsや自分の文章、オープンライセンス資料はそのライセンスの範囲で。

6. 「学習データに入ってる本」でも意味はある

有名な本ほど、モデルは一般知識を持っています。でもそれはインターネット全体の平均圧縮で、章番号や定式を平気で幻覚します。book-to-skill は あなたの手元のコピー に接地するので、ニッチな本・社内文書・新しい版で特に効きます。

チカちゃん的な見立て——これは何の道具か

ちょっと待って。ここまで書くと「便利な変換スクリプト」に見えます。でも扱っている問題は、もう少し深い気がする。

私たちは長いあいだ、「知識を持つ」ことと「知識に手が届く」ことを同一視してきました。本棚に並んでいる＝読める。PDFがある＝参照できる。でもエージェント時代の摩擦は違っていて、存在するのに、仕事の瞬間に届かない。

book-to-skill がやっているのは、本を「読む対象」から「仕事中に呼び出せる道具」へ移すこと。そしてその移し方を、全文dumpでも類似検索でもなく、著者が結晶化した構造の抽出に寄せている。

反対側の見方も置いておきます。

• 過大評価の罠: スキルができても、あなたが枠組みを理解していなければ、エージェントのそれっぽい適用を鵜呑みにするだけになり得る
• 過小評価の罠: 「要約なら自分でできる」と思いがちだけど、毎回のdiscovery loop（目次を辿り直す、戻る、再解釈する）のコストは、人間にもエージェントにも地味に効く
• ビジネス視点: トークン代の節約は表の数字。裏の価値は「同じ本を、チームのエージェントに同じ構造で渡せるか」——ただし著作権と共有ポリシーが先

つまりこれは技術の話でありながら、「私たちは知識をどこに住まわせたいのか」の話でもある。ドーン、というより静かに効いてくるタイプ。

まとめ——まず1冊、手元のコピーで

今日の歩き方を短くすると:

1. git clone で skills フォルダに入れる（pip単体と混同しない）
2. extract.py --check で抽出器を揃える
3. 正当に持つ1冊で /book-to-skill path.pdf slug
4. technical / text を選び、コスト見積もりを見てから生成
5. /slug topic で仕事中に呼ぶ。再配布はしない

日本語の手順記事はまだ少なく、英語READMEをそのまま和訳しても「二系統インストール」や「Discovery Loop Tax」の勘所が抜けやすい——だから今日はそこを厚めに書きました。

答えを急がなくても大丈夫です。本棚の一冊が、ターミナルの隣に座れるようになるかどうか。それ自体が、ちょっとした実験です。

「この本、スキルにしたら何が変わる？」——その問いが残ったら、もう冒険は始まっています。

参考URL

book-to-skill（GitHub） → https://github.com/virgiliojr94/book-to-skill

Install ドキュメント → https://github.com/virgiliojr94/book-to-skill/blob/master/docs/INSTALL.md

Usage ドキュメント → https://github.com/virgiliojr94/book-to-skill/blob/master/docs/USAGE.md

How it works → https://github.com/virgiliojr94/book-to-skill/blob/master/docs/HOW_IT_WORKS.md

Performance（Discovery Loop Tax の実測） → https://github.com/virgiliojr94/book-to-skill/blob/master/docs/PERFORMANCE.md

FAQ → https://github.com/virgiliojr94/book-to-skill/blob/master/docs/FAQ.md

Agent Skills 標準 → https://github.com/agentskills/agentskills

GitHub Trending（weekly） → https://github.com/trending?since=weekly