著者 Matt Connor
技術書をエージェントスキルに変換する方法
PDF、EPUB、DOCX、社内文書を、必要な章だけ読み込むエージェントスキルへ変換します。インストール、トークン予算、ヘッドレス実行、MITライセンスを解説します。
技術書をエージェントスキルに変換すると得られるもの
技術書をエージェントスキルに変換するには、PDF、EPUB、DOCX のエクスポートファイル、またはすでに所有している社内文書のフォルダーをコンバーターに指定します。コンバーターはスキルディレクトリを作成します。そこには、名前付きフレームワークと章のインデックスを記載したエントリーファイルと、質問に必要な場合だけエージェントが読み込む章ごとのファイルが含まれます。書籍全体がコンテキストウィンドウに入ることはありません。インデックスは入ります。
これは、エージェントスキルをゼロから作成する作業とは反対です。後者では、すでに把握している手順を記述します。ここでは知識が存在するにもかかわらず、誰も利用できない状態です。例えば、800ページのベンダー PDF や、執筆者が退職して以来、一度も開かれていないハンドブックなどです。必要なのは、圧縮とインデックス化です。skill という言葉に馴染みがなければ、まずエージェントスキルとは何かを読んでください。
ここで使用するコンバーターは、book-to-skillです。自分のマシン上で実行できる MIT ライセンスのスキルです。2026年8月時点の最新タグは v1.4.0 です。重要なのはツール自体よりも、ツールが生成する構造です。FAQ の前にある最後のセクションでは、同じ構造を手作業で構築する方法を説明します。
トークン予算が設計全体を決める理由
コンテキストウィンドウに貼り付けた書籍は、それを必要とするすべての会話で全体のサイズ分のコストが発生します。スキルでは、エントリーファイルを 1 回読み込むコストに加え、質問が実際に参照する章だけがコストになります。このプロジェクトでは、生成する各ファイルに予算を設定しています。
The data behind this chart
[
{
"label": "SKILL.md entry file",
"tokens": "4,000"
},
{
"label": "One chapter file",
"tokens": "1,000"
},
{
"label": "glossary.md",
"tokens": "1,500"
},
{
"label": "patterns.md",
"tokens": "2,000"
},
{
"label": "cheatsheet.md",
"tokens": "1,000"
}
]エントリーファイル SKILL.md は 4,000 トークン以内に収め、名前付きのフレームワークと章のインデックスを含めます。各章ファイルは約 1,000 トークンで、要求されるまでディスク上に置かれます。補助ファイルも同様で、glossary.md は 1,500 トークン、patterns.md は 2,000 トークン、cheatsheet.md は 1,000 トークンです。
これらの予算は、Claude Code が実際にコンテキストを消費する仕組みに対応しています。スキルの description はスキル一覧に表示されるため、モデルはそのスキルの存在を認識できます。本文はスキルの呼び出し時に読み込まれ、読み込まれた後はセッションの残りの間コンテキストに保持されます。そのため、エントリーファイルの各行は繰り返し発生するコストになります。補助ファイルはエージェントが読む場合にのみ読み込まれるため、章ごとのファイルにするとコストを抑えられます。
このエントリーファイルの数値には、さらに厳しい制限があります。自動圧縮によって長い会話が要約されると、Claude Code は要約後に各スキルの直近の呼び出しを再度追加し、それぞれの先頭 5,000 トークンを保持します。再追加されるすべてのスキルを合わせた予算は 25,000 トークンです。5,000 トークン以内のエントリーファイルなら、圧縮後も全体が残ります。20,000 トークンのエントリーファイルは最初の 4 分の 1 だけが戻り、失われた残りの 3 つの部分がどこかを示す情報はありません。
これが段階的開示です。常にコストに見合う小さなインデックスを用意し、資料の大部分はエージェントが意図的に開くまで別の場所に置きます。Claude Code がコンテキストウィンドウを管理する方法では、この計算の詳細を説明しています。
VPS にコンバーターをリリース固定でインストールする
このスキルは git リポジトリです。使用するエージェントの skills ディレクトリにクローンします。ディレクトリ名がスラッシュコマンドになるため、クローン先のパスは任意ではありません。
git clone --depth 1 --branch v1.4.0 \
https://github.com/virgiliojr94/book-to-skill.git \
~/.claude/skills/book-to-skill--branch はタグを受け付けるため、v1.4.0 をチェックアウトし、それより後のものは取得しません。スキルはエージェントが従う命令の集合であり、その命令に未確認の変更が加わると、サーバー上で実行される内容も変わります。そのため、リリースを固定してください。GitHub Copilot CLI は代わりに ~/.copilot/skills/ を読み込み、Amp は ~/.agents/skills/ を読み込みます。
1 行でインストールできる npx skills add virgiliojr94/book-to-skill もあります。これは最新の内容を取得します。ツールを試す場合に使用してください。再実行する処理には、リリースを固定したクローンを使用します。
次に、サーバーにどの extractor があるか確認します。
cd ~/.claude/skills/book-to-skill
python3 scripts/extract.py --check--check はインストール済みの extractor を表示し、不足している extractor ごとにインストールコマンドを出力します。このパッケージには Python 3.9 以降が必要です。
クローン後にオートコンプリートで /book-to-skill が表示されない場合は、エージェントを再起動してください。Claude Code はセッション開始時点で存在していた skill ディレクトリを監視します。そのため、2 分前に作成した ~/.claude/skills/ はまだ監視対象になっていません。
必要な extractors はどれですか？
Python 以外は必須ではありません。すべての形式に標準ライブラリのフォールバックがあるためです。ただし、フォールバックの性能は劣ります。小規模なサーバーでは、使わない extractors のインストールに時間を費やすことになります。
pdftotextはpoppler-utilsパッケージに含まれ、テキスト中心の PDF を処理します。ほぼ即座に完了します。sudo apt install poppler-utilsでインストールします。pypdfとpdfminer.sixは PDF 用の Python フォールバックです。doclingは、表やコード一覧に価値がある技術系 PDF 用です。プロジェクトの測定では、1 ページあたり約 1.5 秒かかります。ebooklibとbeautifulsoup4を使うと EPUB を正しく読み取れます。これらがない場合、ツールは標準ライブラリのzipfileリーダーにフォールバックします。python-docxは DOCX、striprtfは RTF を読み取ります。- MOBI と AZW ファイルには、Calibre の
ebook-convertが必要です。 ocrmypdfは、テキストレイヤーをまったく持たないスキャン済みの書籍に対して OCR（光学文字認識）を実行します。
Ubuntu 24.04 では、単純な pip3 install pypdf は次のエラーで停止します。
error: externally-managed-environmentこれは pip の故障ではありません。Ubuntu と Debian はシステム Python を apt が管理する状態にしているため、pip はそこへの書き込みを拒否します。利用できる方法は 2 つあります。sudo apt install poppler-utils はバイナリをインストールするため、pip は必要ありません。pdftotext は、ほとんどの文章中心の PDF を単独で処理できます。Python の extractors を使う場合は、仮想環境を作成し、その内部からエージェントを起動してください。これにより、スキルが呼び出す python3 が、パッケージをインストールしたインタープリターになります。
python3 -m venv ~/.venvs/book-to-skill
source ~/.venvs/book-to-skill/bin/activate
pip install "$HOME/.claude/skills/book-to-skill[pdf,epub,docx]"
claudeリポジトリでは、pdf、epub、docx、rtf、technical、all の extras が宣言されています。このうち technical は docling です。プロジェクトのインストールページには pip install "book-to-skill[pdf,epub,docx]" も示されていますが、2026 年 8 月時点では、その名前は PyPI に公開されていません。そのため、上記のように自分の checkout からインストールしてください。
docling は、書籍で必要になるまでインストールしないでください。機械学習スタックを依存関係として取り込むため、小規模なプランではインストール前に空きディスク容量を確認してください。
ドキュメントのフォルダーを処理する（ヘッドレス実行を含む）
このコマンドでは、ファイル、フォルダー、引用符で囲んだ glob、または複数のパスを指定し、その後に任意の skill 名を指定します。1 つのディレクトリに置けるものなら何でも使用できます。RFC セット（Request for Comments。インターネットプロトコルを定義するドキュメント）も含まれます。
/book-to-skill ~/library/platform-docs/ platform-handbook
/book-to-skill "~/books/*.epub" my-library
/book-to-skill ~/papers/paper1.pdf ~/notes/export.txt unified-researchshell が skill に渡す前に glob を展開しないよう、glob は引用符で囲んでください。既存の skill ディレクトリをコマンドに指定すると、別の skill を作成せず、その skill に新しいソースを統合します。
対話形式で実行すると、いくつか質問されます。資料が技術的な内容か、テキスト中心かを尋ねられ、使用する extractor が決まります。参照用の深さにするか、学習用の深さにするかを尋ねられ、章ごとの予算が決まります。skill の名前と、配置する skills root も指定します。また、生成前にトークン数と所要時間の見積もりを表示し、確認を待ちます。
ヘッドレス実行では、これらの質問に回答する人がいません。ユーザーが呼び出せる skill は claude -p でも動作します。プロンプト文字列にスラッシュコマンドを含めると、実行開始前に Claude Code が展開します。そのため、同じプロンプト内で質問への回答を指定してください。
claude -p "/book-to-skill ~/library/platform-docs/ platform-handbook
The sources are technical. Use reference depth. Write the skill to
~/.claude/skills/. Do not publish it to GitHub. Proceed without asking me." \
--allowedTools "Bash,Read,Write,Edit"--allowedTools は、実行に必要なツールを事前承認します。ターミナルが接続されていない状態で権限プロンプトが表示されると、実行が完了しないためです。--output-format json を追加すると、結果に total_cost_usd が含まれます。これはクライアント側の見積もりであり、請求額ではありません。
抽出処理では、モデルがソースを読み取る前に、すべてのソースを /tmp 配下の一時作業ディレクトリに統合します。実行の最後に、このディレクトリを削除します。抽出に失敗したソースはスキップされるため、バッチ処理自体は継続します。そのため、指定したファイル数より少ないファイルを読み取った状態でも、実行が成功と報告される場合があります。最終レポートのファイル一覧を、フォルダー内の内容と比較してください。章が欠落している場合、通常はソースが不足しています。
実行には、agent に渡しても問題ない server を指定してください。権限に関する説明は、VPS 上で Claude Code を安全に実行する を参照してください。
出力先と coding agent が見つける仕組み
生成された skill は skills root に配置されます。重要なのは 2 つです。
~/.claude/skills/<skill-name>/は個人用で、そのマシン上のすべてのプロジェクトから利用できます。.claude/skills/<skill-name>/はリポジトリ内にあり、リポジトリとともに移動します。
どちらにも SKILL.md と、章ごとに 1 ファイルを収めた chapters/ ディレクトリ、および補助ファイルがあります。ディレクトリ名がコマンドになるため、~/.claude/skills/platform-handbook/ で /platform-handbook を利用でき、続けてトピックまたは通常の質問を指定できます。
利便性ではなくライセンスに基づいて root を選択してください。購入した書籍から作成した skill は個人用ディレクトリに配置します。自分のチームが作成したドキュメントから作成した skill はリポジトリに配置します。すると、複数のリポジトリで 1 つの skill を共有することが次に解決すべき課題になります。
skill を追加するたびに増えるコストがあります。各 skill の説明は skill 一覧に残り、モデルがその skill を使用するか判断します。結合された説明文はエントリごとに 1,536 文字で切り詰められ、一覧全体にも上限があります。書籍から作成した skill が 10 個あると、10 個の説明文がこの上限を奪い合います。名前を指定して常に呼び出す skill には、生成された frontmatter に次の 1 行を追加してください。
---
name: platform-handbook
description: Frameworks and chapter index from the internal platform handbook.
disable-model-invocation: true
---disable-model-invocation: true を指定すると、説明文がコンテキストにまったく含まれなくなります。それでも /platform-handbook と入力すれば、skill 全体が読み込まれます。自動検出は利用できなくなりますが、コンテキストウィンドウを静かに保てます。
ライセンス: MIT が適用されるのはコンバーターであり、書籍ではありません
この点は正確に扱ってください。ここでの問題は技術的なものではありません。
- MIT ライセンスが適用されるのは、コンバーターのコードとその skill 定義です。コンバーターに入力する文書については何も定めていません。
- 購入した書籍を、自分が管理するハードウェア上でコンバーターにかけることは、自分の所有するコピーから自分用のノートを作成する行為です。
- 結果を公開することは配布にあたります。ツールに付与された MIT ライセンスによって、他者の書籍から派生したものを配布する権利が得られるわけではありません。
- 出力は二次的著作物です。フレームワークや章ごとの要点も原著作物の影響を受けており、二次的著作物にも原著作物の著作権が適用されます。
- 再配布できない資料から作成した skill は、それを作成したマシン内に保持してください。公開リポジトリに置いてはいけません。チームで共有する marketplace にも置いてはいけません。
- 原資料が自分の著作物である場合、またはオープンライセンスである場合に公開してください。たとえば、チームが作成したドキュメントや、再配布を認める条件の標準規格です。
このツールは、この原則を前提に構築されています。書籍の内容は同梱せず、抽出処理はローカルで実行します。また、公開手順ではリポジトリの可視性を独立した質問として確認し、推測で決めず、単独の public または private だけを受け付けます。このプロンプトはライセンスに関する判断として扱ってください。実際にその判断を求めているためです。
社内ハンドブックには、もう1つ問題があります。誰もが認めたがらないほど頻繁に認証情報が含まれており、コンバーターによって、誰も開かない PDF がエージェントの要求時に読み込まれるファイルへ変わってしまいます。生成されたファイルはコミットする前に一度読み、AI エージェントから秘密情報を除外するも参照してください。
1 回の変換にかかる費用
以下の数値は、私たちが測定したものではなく、プロジェクトが公開している独自の測定結果です。
The data behind this chart
[
{
"label": "Think Python 2",
"cost_usd": 0.88
},
{
"label": "Working Backwards",
"cost_usd": 0.96
},
{
"label": "Pro Git",
"cost_usd": 1.23
},
{
"label": "Moby-Dick",
"cost_usd": 1.42
}
]プロジェクトが測定した 4 冊では、1 回の変換費用は 0.88 ～ 1.42 US ドルでした。Pro Git は 1.23 です。これらの数値は Claude Sonnet 4.5 で測定されました。トークン数は tiktoken から取得し、cl100k_base を使用しています。2026 年 8 月時点で、プロジェクトの docs/performance.md に公開されています。実際の費用は、使用するモデルと料金によって変わります。
また、このプロジェクトの資料では、スキルから 1 つの質問に回答する場合、書籍全体をコンテキストに貼り付ける場合と比べて、必要なトークン数が 24 ～ 51 分の 1 になると説明されています。これは保証値ではなく、削減幅の目安として捉えてください。書籍と質問の内容によって変わるためです。ただし、構造上の要点は変わりません。変換の費用は 1 回だけ発生しますが、コンテキストダンプの費用は、その書籍を必要とする会話のたびに発生します。
PDFを貼り付けたり、RAGインデックスを作成したりするのではなぜいけないのでしょうか？
貼り付けは機能します。1つの文書について1つの質問に答える場合には、適切な方法です。しかし、同じ書籍を火曜日に使い、金曜日にも再び使う場合は、毎回その全体サイズ分のコストが発生するため、適切な方法ではなくなります。
検索（RAG（retrieval augmented generation））は、クエリの実行時に検索し、入力した語句に一致する抜粋を返します。正確な一文が必要な場合には有効です。一方、必要な情報が章全体にまたがるフレームワークの場合は、1つの抜粋に収まらないため弱点があります。Skillは変換時にこの抽出を1度だけ実行し、抜粋ではなく構造を保存します。
率直に言えば、生成されたSkillはモデルが作成した情報量を失った要約です。学習補助として使うものであり、原典はあくまで原典です。正確な文言が法的またはプロトコル上の効力を持つ場合は、PDFを保持し、そこから引用してください。Skill、MCP server、rules fileの比較では、それぞれの方法を使うべき場面を説明しています。
障害時の挙動と表示されるメッセージ
スキャンした PDF から何も生成されない。 抽出処理は冒頭のページでテキストレイヤーを確認し、画像だけのページを 400 ページ処理し続けるのではなく、説明を表示して停止します。最初に ocrmypdf input.pdf output.pdf を実行し、その出力ファイルを入力してください。
pip でインストールできない。 Ubuntu 24.04 の error: externally-managed-environment は、システムの Python を保護するための apt の動作です。上記の仮想環境を使用するか、poppler-utils をインストールして pip を完全に使わないでください。
章の分割が正しくない。 章の検出では、Chapter 7 やその言語別の表記など、明示的な見出しを探します。セクション名だけ、またはローマ数字を使う本では分割結果が不正確になります。推測に任せず、章の開始位置を実行時に指定してください。
コマンドが存在しない。 オートコンプリートに /book-to-skill が表示されない場合は、セッション開始後に skills ディレクトリが作成されています。エージェントを再起動してください。
Docling の処理に時間がかかりすぎる。 1 ページあたりおよそ 1.5 秒かかるため、長い本では数分の CPU 時間が必要です。共有サーバーでは、その処理がほかのホスト中の処理とリソースを競合します。実行時にコンテンツの種類を尋ねられたら「text-heavy」と回答するか、scripts/extract.py を自分で実行する場合は --mode text を渡してください。--mode technical が docling を選択する回答です。
ソースが何も表示されずに消える。 読み取れないファイルは、バッチ処理を完了できるようにスキップされます。そのため、実行結果は入力したソース数より少ないソースに対する成功を報告します。このことを確認できるのは、最終レポートのファイル一覧だけです。
手作業で同じパターンを適用する
このツールは作業を簡便にするためのものです。転用できるのは構造であり、所有している参考資料であれば、テキストエディターでも同じ構造を作成できます。
- エントリーファイルを1つ作成し、コンバーターが対象とする4,000トークン前後に収めます。そこには、指定された概念を正確な表現で記載します。さらに、すべての詳細ファイルと、各ファイルに含まれるトピックを列挙したインデックスを追加します。
- 資料をおおよそ1,000トークンずつのファイルに分割します。各ファイルは1つのトピックだけを扱い、ファイル名だけで内容が分かる名前を付けます。
- エントリーファイルから、それらの各ファイルについて説明します。説明は、そのファイルを読む条件を示す文の中に記載します。
多くの人が省略するのがこの Step 3 ですが、この手順がパターンを機能させます。エージェントはインデックスを読んで開くファイルを選択します。そのため、インデックスに記載されていないファイルをエージェントが開くことはありません。インデックスが成果物であり、章ファイルは格納場所です。
エントリーファイルを圧縮後の予算内に収めれば、長時間のセッションでも構造全体を維持できます。コンバーターがファイルを作成した場合でも、あなたが作成した場合でも、このルールは変わりません。
FAQ
購入した書籍から作成した skill を公開できますか？
その書籍のライセンスが再配布を許可している場合を除き、公開できません。コンバーターに適用される MIT license はコンバーターのコードを対象とするもので、入力する資料は対象外です。生成された skill は書籍の二次的著作物に当たります。~/.claude/skills/ に保存し、自分のマシン内で使用してください。自分で作成したドキュメントや、オープンライセンスのソースであれば公開できます。また、このツールはリポジトリの公開設定を独立した項目として確認し、値として public または private のみをそのまま受け付けます。そのため、公開するかどうかを意図的に判断できます。
docling は必要ですか。それとも pdftotext で十分ですか？
poppler-utils の pdftotext で、文章の抽出には十分であり、ほぼ即座に完了します。書籍の価値が表やコード一覧にある場合は docling をインストールしてください。プレーンテキストの抽出器では、まさにそれらが失われるためです。トレードオフは速度です。このプロジェクトでは、docling の処理時間を 1 ページあたり約 1.5 秒と測定しています。そのため、300 ページのマニュアルでは VPS 上で CPU 処理に数分かかります。
VPS で externally-managed-environment により pip が失敗するのはなぜですか？
Ubuntu 24.04 と現在の Debian では、システムの Python が apt によって管理されていることを示します。そのため pip はシステム環境へのインストールを拒否し、error: externally-managed-environment と表示します。python3 -m venv ~/.venvs/book-to-skill で virtual environment を作成し、それを有効化してから、extractor をその環境にインストールしてください。その後、同じ shell から agent を起動します。skill は python3 を呼び出すため、PATH 上にある interpreter を使用します。この時点では、PATH 上の interpreter は virtual environment 内のものです。
生成した skill が slash command として表示されないのはなぜですか？
原因は 2 つあります。command name は directory name から決まるため、skill は ~/.claude/skills/<name>/SKILL.md または .claude/skills/<name>/SKILL.md に配置し、SKILL.md と正確に記述する必要があります。パスが正しい場合は、agent を再起動してください。Claude Code は、すでに監視している skill directory 内の編集を検出します。しかし、session の開始後に作成した skills directory は、まったく監視されません。