book-to-skillで技術書PDFをClaudeスキル化する方法

Claude Code や GitHub Copilot CLI で日常的にコーディングエージェントを使うようになってから、「よく参照する技術書 PDF や社内ドキュメントを、毎回コンテキストに投入するのはトークンがもったいない」と感じたことはないでしょうか。とくに 300 ページを超える技術書を丸ごとエージェントに読ませようとすると、目次の再フェッチや章の往復で入力トークンだけがみるみる膨らみ、肝心の応答に使える余力が減っていきます。

Anthropic の Agent Skills が正式リリースされて以降、「よく読むドキュメントはスキル化して常駐させる」というアプローチが注目を集めています。一方で、Skills を自作するのは仕様理解・章立て・用語集の設計まで手作業でこなす必要があり、初見のエンジニアにとってはハードルが高いのも事実です。

そこで登場したのが、本記事で紹介する OSS「book-to-skill」です。技術書 PDF や社内ドキュメントを Claude Code / GitHub Copilot CLI / Amp 共通の Agent Skill フォーマットに変換し、以降は該当章だけをオンデマンドで読み込ませられるよう構造化してくれます。作成から約 4 か月で GitHub スター 23,000 超（virgiliojr94/book-to-skill、repo-meta.json 記録時点 23,434）を集めた注目リポジトリです。

しかしいざ「自社に導入すべきか」を検討し始めると、「単発の PDF → Markdown 変換ツールとどう違うのか」「著作権上、どこまで許されるのか」「スキャン PDF はいけるのか」「メンテナンスは健全か」といった疑問が次々と湧いてきます。公式 README は英語で情報密度が高いため、初見で全体像をつかむのは容易ではありません。

本記事では、公式リポジトリ・公式ドキュメント（docs/how-it-works.md / docs/performance.md / docs/usage.md）の内容だけを根拠に、book-to-skill の全体像を「初見エンジニアの意思決定支援」という視点で整理します。機能・アーキテクチャ・Discovery Loop Tax によるトークン削減モデル・類似 OSS との差分・採用時のリスクまでを 1 本にまとめ、社内での「試験導入する／見送る／別ツールを検討する」の判断材料を提供します。

なお本記事は動作検証やインストール実験を伴わず、公開ドキュメントの記述のみを情報源としています。数値や仕様は repo-meta.json および公式ドキュメントの記載時点のもので、対象リポジトリは archived=false / fork=false / disabled=false（gh api /repos/virgiliojr94/book-to-skill の返却値）の通常運用リポジトリです。

book-to-skill とは何か

book-to-skill は、技術書 PDF・社内ドキュメント・ソースツリー等のまとまった文書群を、コーディングエージェントで共通利用できる Agent Skill（SKILL.md を中心とするフォーマット）に変換する OSS です。README の説明を要約すると、「一度スキル化してしまえば、以降は必要な章だけをオンデマンドで読み込めるため、コンテキスト消費を圧倒的に減らせる」ことが最大の売りとなっています（README）。

リポジトリの基本情報

まず判断材料として、リポジトリの基本情報を整理します。以下は gh api /repos/virgiliojr94/book-to-skill の返却値（repo-meta.json）に基づく執筆時点のスナップショットです。

作成は 2026 年 5 月、約 4 か月で 23,000 以上のスターを集めた比較的新しいリポジトリです。ライセンスは寛容な MIT で、コミット活動は現在も継続中（アーカイブ・フォークではない）です。Python 製で、内部のドキュメント抽出パイプラインもすべて Python スクリプトとして提供されています。

解決している課題「Discovery Loop」

book-to-skill が解決しようとしているのは、エージェントで長い PDF を扱うときに生じる Discovery Loop と呼ばれるオーバーヘッドです。公式ドキュメントでは、大きな PDF をそのままエージェントに渡した場合、エージェントは「読む」だけでなく、毎ターン目次を再フェッチし、章の往復・再処理を繰り返すことで、実質的に大量のトークンを繰り返し支払っている、と説明されています（docs/how-it-works.md）。

book-to-skill はこの構造化コストを「変換時に一度だけ」支払うアプローチをとります。事前に本を「フレームワーク・決定ルール・アンチパターン・章別ファイル」の構造化スキルに蒸留しておき、以降はエージェントが該当章だけをオンデマンドで読み込みます。README では利用フローが 3 ステップで示されており、たとえば /book-to-skill ./my-book.pdf のように対象パスを指定するとスキルが生成され、以降は /my-book replication のようにスキル内トピックへ直接問い合わせることができます。

生成される Agent Skill の中身と構造

「変換した結果、具体的に何が手元に残るのか」は導入判断の基本情報です。book-to-skill は単一ファイルではなく、複数のファイルを持つ 1 つのスキルディレクトリを生成します。README の「What it generates」に沿って整理すると次の 5 種類になります。

5 種類の生成ファイルと役割

ポイントは、SKILL.md に「本全体のメンタルモデル」を圧縮して常時ロードし、詳細は必要になった章だけを都度読み込ませる二階建てになっていることです。用語集・パターン・チートシートも独立ファイルとして切り出されており、質問の性質（用語確認・パターン適用・チートリファレンス）に応じて必要最小限のコンテキストだけを引き寄せられます。

ホスト別の保存先ディレクトリ

生成物は使用するエージェントに合わせて保存先が変わります。README の記載では次のパスが標準です。

• Copilot CLI: ~/.copilot/skills/<slug>/
• Amp / クロスエージェント: ~/.agents/skills/<slug>/
• Claude Code: ~/.claude/skills/<slug>/

いずれも Agent Skills の共通仕様に沿ったディレクトリ配置のため、同じスキルを複数ホストで使い回しやすい構造になっています。

オンデマンド章読み込みの動作イメージ

README には、生成されたスキルの利用例として次のようなコマンド呼び出しが示されています（README の抜粋・改変なし）。

/designing-data-intensive-apps                  # コアメンタルモデルをロード
/designing-data-intensive-apps replication      # 特定トピックを検索・解説
/designing-data-intensive-apps ch05             # 章 5 を精読
/designing-data-intensive-apps "what chapters do you have?"

サブコマンドなしで呼び出すとコアの SKILL.md のみがロードされ、replication のようなトピック名や ch05 のような章番号を追加すると、その章ファイルだけが追加で引き込まれます。書籍以外にも、README では社内 ADR・ランブック・ブランドガイド・研究論文・仕様書（RFC / API 契約 / コンプライアンス文書）など、「頻繁に読み返すが毎回開くのが面倒」なドキュメント全般が対象になると述べられています。

アーキテクチャ｜決定論的 extractor と spec-driven generator

「LLM に丸ごと投げて要約させる」のではなく、決定論的な抽出と仕様駆動の生成をきれいに分けているのが book-to-skill 設計の核です。公式の docs/how-it-works.md では、パイプラインを大きく 2 つの半分に整理しています。

決定論的 Python extractor

前半は、ドキュメントを「クリーンなテキスト＋メタデータ」に変換する Python の抽出器群です。書籍タイプに応じて次のように抽出器を切り替えます。

• 技術書（テーブル・コードブロックを含む書籍）: Docling をベースにテーブル・コードを Markdown で保持（103 ページの技術書で 164 秒程度が目安）
• 一般テキスト中心の書籍: pdftotext（poppler） / pypdf / pdfminer など軽量な抽出器で瞬時に取り込み
• スキャン PDF: 未対応。先頭ページでテキストレイヤの有無を判定し、無ければ即中断する堅牢な仕様（利用者側で ocrmypdf などによる OCR 前処理が必要）

対応フォーマットは PDF・EPUB・DOCX・TXT・Markdown・reStructuredText・AsciiDoc・HTML・RTF・MOBI / AZW / AZW3 と幅広く、python3 scripts/extract.py --check で必要な抽出器のインストール状況をまとめて確認できるユーティリティも用意されています。中間成果物は /tmp/book_skill_work/full_text.txt と /tmp/book_skill_work/metadata.json に集約され、実行後はクリーンアップされます。

spec-driven generator

後半は、抽出テキストを Agent Skill に構造化する生成フェーズです。ここではエージェント（Claude 等）が SKILL.md に記述された仕様に従い、章別サマリ・用語集・パターン集・チートシート・コアの SKILL.md を順に生成していきます。ポイントは、生成ロジックそのものが SKILL.md にドキュメント化されている「spec-driven」設計になっていることです。ブラックボックスの LLM 変換ではなく、「何をどう生成するか」の仕様が明示され、他エージェントでも再現可能な形になっています。

設計原則として公式ドキュメントでは、Density over completeness（要約の密度を優先）、Practitioner voice（実践者の口調）、Front-loaded SKILL.md（重要情報を先頭に集中）、On-demand chapters（章はオンデマンド）、Never raw text（生文コピーではなく合成・要約）の 5 つが挙げられています。

抽出ベンチマーク（103 ページ技術書）

公式の docs/how-it-works.md には、同じ 103 ページの技術書 PDF を別方式で抽出したときの比較値が掲載されています。CPU のみでの実測値です。

トークン量はほぼ同じでも、Docling を使うとテーブル 48 個・コードブロック 36 個が Markdown 構造として保持されます。「技術書はテーブルとコード保持のために Docling、一般書はスピード重視で pdftotext 系」と、書籍の性質に応じて自動的にトレードオフを取れるよう設計されているのが分かります。

Discovery Loop Tax｜24〜51 倍のトークン削減モデル

トークン削減の根拠として、book-to-skill が独自に提示しているのが Discovery Loop Tax という概念です。詳細は docs/performance.md にまとまっており、tools/discovery_tax.py を使うことで実測値を再現できます。

Discovery Loop とは何か

エージェントが大きな PDF を毎ターン参照するとき、実際には次のようなオーバーヘッドが発生します。

• 目次（ToC）を毎ターン再フェッチする
• 章を行き来しながらコンテキストを再構築する
• 抜き出した領域を再度処理する

こうした「毎ターン繰り返し発生するコスト」を Discovery Loop と呼び、book-to-skill はこの構造化コストを「事前の変換時に 1 回だけ支払う」設計にすることで、以降のクエリを「答えに比例した最小トークン」に抑えます。

実測トークン比較

docs/performance.md には、1 つのターゲット質問に必要なコンテキスト投入トークン量を、3 冊の書籍で比較した結果が示されています。book-to-skill 経由の場合は、常駐する SKILL.md 約 4K + 該当章 1K ≒ 約 5,000 トークンで安定します。

python3 tools/discovery_tax.py --full-text /tmp/book_skill_work/full_text.txt --target-chapter 5 のようなコマンドで、同じロジックを手元でも再計算できます（docs/performance.md、コマンド抜粋・改変なし）。

context-dump との差（24〜51 倍）は「毎ターン繰り返し発生する差」で、章サイズが大きい書籍ほど拡大します。discovery-loop との差（2.4〜15.6 倍）は「一度限りの差」ですが、同じく章が大きいほど有利になります。「大きな書籍・繰り返し使う書籍ほど、変換コストを上回るリターンが得られる」というのが、公式が示している定量的な主張です。

フル変換のコスト目安

同ドキュメントには、変換 1 回にかかる推定コストも掲載されています。Claude Sonnet 4.5（$3 / $15 per MTok）で計算した参考値です。

「本 1 冊あたりおおむね $1 前後」で、以降は該当章のみで済むイメージです。変換は一度きりで、あとは同じスキルを繰り返し利用できるため、ヘビーユースの書籍ほど回収期間が短くなります。

セットアップと基本コマンド（ドキュメントベース）

ここではあくまで公式 docs/usage.md と README の記述をベースに、導入と基本操作の全体像を整理します。本記事では実機での動作検証は行っていないため、実際に導入する際はコマンドオプションやパスを最新の公式ドキュメントで確認してください。

インストール

インストール方法は公式で 2 系統示されています。1 つ目はクロスエージェント CLI 経由の 1 コマンドインストール、2 つ目は手動クローンです。以下は README からの抜粋（改変なし、README 参照）です。

# クロスエージェント CLI 経由（推奨・1 コマンド）
npx skills add virgiliojr94/book-to-skill

# 手動クローン（Claude Code の場合）
git clone https://github.com/virgiliojr94/book-to-skill.git ~/.claude/skills/book-to-skill
# Copilot CLI: ~/.copilot/skills/  ／  Amp・クロスエージェント: ~/.agents/skills/

npx skills add は他ホストからのインストールにも対応しており、公開したスキルを npx skills add https://github.com/<you>/<your-book-slug> の形で共有できます。

4 つのモードの使い分け

docs/usage.md には、/book-to-skill <path|folder|glob>... [skill-name-slug] の基本形に加えて 4 種類のモードが整理されています。

1. 単一ファイル・複数ファイル・フォルダ・glob をまとめて 1 つのスキルに変換する基本モード
2. update / fold-in モード: 既存のスキルフォルダに新資料を追加してマージ
3. analyze-only / generate-from-analysis の分離実行: 分析フェーズと生成フェーズを分けて実行
4. GitHub パブリッシュ: 変換後に対話で GitHub リポジトリへの push を尋ねる。gh repo create はデフォルト --private で、「public」の一語のみで public リポジトリになる

「単発で試したいときは 1 の基本モード、既存書籍にサプリメント資料を追加したい場合は 2 の fold-in、コスト最適化のために分析と生成を分けたい場合は 3 の分離実行、社内で共有したい場合は 4 のパブリッシュ」という使い分けです。Copilot CLI では書き込み直後に /skills reload の実行が必要になる場合があり、Claude Code / Amp は次回セッションから認識されるとの記述もあります。

対応フォーマットと制約

対応フォーマットは PDF・EPUB・DOCX・TXT・Markdown・reStructuredText・AsciiDoc・HTML・RTF・MOBI / AZW / AZW3 と幅広く、それぞれ以下の抽出器を選択します（docs/how-it-works.md）。

• PDF（テキスト中心）: pdftotext（poppler）／ pypdf ／ pdfminer.six
• PDF（技術書）: Docling
• スキャン PDF: OCR 必須（ocrmypdf などで前処理後に変換）
• EPUB: ebooklib + beautifulsoup4（最良）／ stdlib zipfile（フォールバック）
• DOCX: python-docx ／ stdlib ZIP + XML
• HTML: beautifulsoup4 ／ stdlib html.parser
• RTF: striprtf ／ 正規表現
• MOBI / AZW / AZW3: Calibre の ebook-convert（pip ではなく外部アプリ）

スキャン PDF はコンバータ側でサポートされておらず、テキストレイヤがないと先頭ページで中断される仕様です。ここは導入前に把握しておきたい制約と言えます。

類似 OSS との比較｜導入判断のための差分整理

book-to-skill を採用するかどうかを判断するには、「近い立ち位置の OSS と何が違うのか」を並べて見るのが近道です。ここでは公式リポジトリ情報と owner/name レベルで確認できる 3 つの代表例を、狙いが最も近いものから順に取り上げます。

kangarooking/cangjie-skill との違い（最も近い立ち位置）

もっとも狙いが近いのが kangarooking/cangjie-skill です。書籍だけでなく 長尺動画・ポッドキャスト・講義・インタビュー・演説など、字幕や文字起こしが得られるあらゆる長尺コンテンツ を Claude Code / Cursor 用の Agent Skill に変換する OSS で、スター数は 8,500 前後・ライセンスは GNU AGPL v3.0 です。日本語圏でも既に紹介記事があり、本サイトでも書籍・動画をSkillsに蒸留するOSS「cangjie-skill」の仕組みとして深掘り記事を公開しています。

両者の違いは、大きく次の 3 点です。

• 対象メディアの範囲: book-to-skill は PDF / EPUB / DOCX / TXT / Markdown / HTML など文書系フォーマットに特化しています。一方 cangjie-skill は書籍に加えて、字幕・文字起こしがある動画・ポッドキャスト・講義・インタビュー・演説まで対象に含めます。動画・音声由来の一次資料を扱いたい場合は cangjie-skill 側の守備範囲になります。
• パイプライン設計思想: book-to-skill は 決定論的 Python extractor（Docling / pdftotext 系）と spec-driven generator（Claude が SKILL.md 仕様に沿って構造化）の 2 分割で、抽出と生成の責務がはっきり分かれています。cangjie-skill は「RIA-TV++」と呼ばれる 7 段階パイプライン（全体理解 → 並列抽出 → 三重検証 → RIA++ 構築 → Zettelkasten 連携 → ストレステスト → デリバリー）で、抽出と検証・構造化を多段で一体化した設計です。
• 定量根拠の提示方法: book-to-skill は Discovery Loop Tax（context-dump 比 24〜51 倍・discovery-loop 比 2.4〜15.6 倍のトークン削減）を tools/discovery_tax.py で再現可能な実測トークンで示しています。cangjie-skill 側の主要指標は「検証通過率 25〜50%」「1 冊あたり 10〜25 個のスキル抽出」といった生成品質・粒度の指標で、トークン削減量そのものは主指標として掲げられていません。

「文書系フォーマットに絞って、削減効果を数値で説明したい」なら book-to-skill、「動画・ポッドキャストも含めて、多段検証で品質を担保したスキルを作りたい」なら cangjie-skill、という選び分けが出発点になります。

github/awesome-copilot の convert-pdf-to-md との違い

github/awesome-copilot は、GitHub Copilot 向けの汎用スキル・エージェント・設定を集めたコミュニティカタログです。この中に skills/convert-pdf-to-md という「PDF を Markdown に変換するだけの単発スキル」が含まれます。カタログ側は 38,000 スター超と広く使われていますが、内包する PDF スキルはあくまで 変換して終わり の位置付けで、章別ファイル・オンデマンドロード・トークン削減モデルは持ちません。

一方 book-to-skill は「変換して Markdown を吐く」のではなく、SKILL.md を中心としたオンデマンド構造化スキルを生成する点が本質的に異なります。生成物がそのままエージェントの「常駐知識ベース」になり、章別読み込みまでを設計内に含めているため、読解の効率化が主目的の場合は book-to-skill の方向性のほうがマッチします。

ComPDFKit/compdf-skills との違い

ComPDFKit/compdf-skills は、Claude Code / Cursor / Copilot / OpenCode など 39+ のコーディングエージェント向けに、「PDF の変換・編集・分割・挿入・比較・圧縮」等の操作スキルを提供する OSS です。名前が近いため book-to-skill と混同しやすいのですが、狙いは大きく異なります。compdf-skills は「PDF そのものを操作する」ツール集で、コーディング作業に PDF 加工の効率化を持ち込むのが目的です。

book-to-skill は逆に、PDF の中身を長期的にクエリ可能なスキル資産に変えることに特化しています。スター数は 100 台、ライセンスは執筆時点で未設定で、成熟度・利用可能な用途もかなり異なります。「PDF を編集・加工したい」なら compdf-skills、「PDF から読解効率化のためのスキル資産を作りたい」なら book-to-skill、という切り分けになります。

どんなケースでどれを選ぶか

まとめると、4 者の使い分けは次のように整理できます。

• 単発で PDF を Markdown 化したい → github/awesome-copilot の convert-pdf-to-md（またはより単純な変換ツール）
• PDF ファイルそのものを編集・分割・比較したい → ComPDFKit/compdf-skills
• 書籍だけでなく動画・ポッドキャスト・講義など長尺コンテンツもまとめてスキル化したい → kangarooking/cangjie-skill（多段パイプラインで生成品質を担保する設計）
• PDF や社内ドキュメントを、繰り返しクエリするためのスキル資産に変え、トークン削減の効果を定量的に説明したい → book-to-skill

Discovery Loop Tax の削減モデルや章別ロード設計は、繰り返し利用する書籍・ドキュメントほど効いてきます。「1 回変換して終わり」の使い方であれば汎用の PDF → Markdown 変換で足りるケースが多く、扱う一次資料が動画・音声中心なら cangjie-skill 側の設計のほうが素直にフィットします。

採用判断のチェックポイントと注意点

ここまでで機能・アーキテクチャ・類似 OSS との差分は整理できました。最後に、実務投入前に確認しておきたい「メンテナンス」「著作権」「現時点の制約」の 3 点を、公式ドキュメントの記述に基づいて整理します。

メンテナンス指標の読み方

repo-meta.json の値および 公式リポジトリ の状態から、執筆時点のメンテナンス指標は次のとおりです。

• スター数: 23,434（作成 2026 年 5 月から約 4 か月）
• フォーク数: 2,477
• 最終 push: 2026-08-19（本記事執筆時点で直近数日以内）
• ライセンス: MIT
• ステータス: archived=false、fork=false、disabled=false（通常運用中）
• 主要言語: Python

短期間でスターが集中的に積み上がっており、コミット活動も継続中で、フォークも 2,000 以上と多めです。総合的にみて「活発にメンテナンスされているリポジトリ」の指標を満たしていると読めます。とはいえ、公開から半年程度と歴が浅く、大幅な API 変更が入る可能性は否定できないため、社内利用時は依存バージョンを固定する運用が現実的でしょう。

著作権・フェアユース

導入判断の要となるのが著作権の扱いです。README には次の趣旨で明記されています。

• book-to-skill は 書籍本体を配布しないコンバータであり、ユーザーが自分で所有・購入した本を対象にする
• 処理はローカル実行で、ファイルは本ツールからアップロードされない（ただし変換に使う LLM がクラウドの場合、そのプロバイダのデータ規約が別途適用される）
• 生成スキルは「手書きの学習ノート」相当のデリバティブ。Quality Rule #7 により、生の本文コピーは含めない設計
• 著作権のある第三者書籍から生成したスキルの再配布は不可（private リポジトリでの運用を推奨）

つまり、社内ドキュメント・自社所有の本・オープンライセンス資料をスキル化して社内で使う分には比較的自由度が高い一方、市販の第三者書籍から作ったスキルを public リポジトリで公開したり、社外に配布したりする使い方は避けるべきです。GitHub パブリッシュモードのデフォルトが --private になっているのも、この方針を反映した挙動と読めます。

現時点の制約

もう 1 点、導入前に押さえておきたいのが技術的な制約です。

• スキャン PDF は非対応。先頭ページでテキストレイヤの有無を判定し、無ければ即中断される仕様（docs/how-it-works.md）
• 生の本文コピーはスキルに含まれない（Quality Rule #7）ため、原文の引用が業務要件になる用途（法務レビュー等）には向かない
• 生成コストが発生する（Claude Sonnet 4.5 換算で 1 冊あたり約 $1）。トライアンドエラーで再生成する場合はコストが積み上がる
• Copilot CLI では /skills reload を実行する場合がある（Claude Code / Amp は次回セッションから認識、docs/usage.md）
• GitHub パブリッシュ機能は gh CLI 認証を前提とする

いずれも「使えないほどの制約」ではありませんが、社内で複数書籍を一括変換する運用を想定しているなら、コスト概算・スキャン PDF の OCR 前処理フロー・スキル更新時のフォールドインルールをあらかじめ設計しておくと安全です。

まとめ｜book-to-skill が向くケース／向かないケース

最後に、初見エンジニアが自プロジェクトへの適用可否を判断するための軸を整理しておきます。

• 向くケース: 特定の書籍・社内ドキュメントを Claude Code / Copilot CLI / Amp で繰り返し参照する運用がある。オンデマンド章ロードによってコンテキストを節約したい。社内 ADR・ランブック・ブランドガイド・仕様書などを共通スキル資産化したい
• 向かないケース: PDF を単発で Markdown 化したいだけ。スキャン PDF がメインで OCR 前処理まで用意する余力がない。原文の引用そのものが必要な用途（法務レビュー等）。第三者書籍から作ったスキルを社外配布したい

book-to-skill の強みは「変換して終わり」ではなく、Agent Skills 標準に沿った構造化された知識資産を生成し、それを複数ホストで再利用できる点にあります。Discovery Loop Tax モデルによる 24〜51 倍のトークン削減は、繰り返し参照する書籍ほど効きます。まずは社内 ADR や 1 冊の技術書といった小さなスコープで試験導入し、変換コストと運用フローの実態を把握してから、全社的な利用範囲を広げていくのが現実的な進め方でしょう。

関連情報

Claude Code スキルや OSS を活用した業務効率化・受託開発をご検討中の方は、お問い合わせフォーム からご相談ください。要件の整理段階から、社内ドキュメントのスキル化・PoC の設計まで対応可能です。

Claude Code / Copilot CLI / Agent Skills を活用した案件を探しているエンジニアの方は、Workee でフリーランス案件を探す もあわせてご覧ください。