SSD Nodes Learn Hosting plans →
ガイド Matt Connor著者 Matt Connor

技術書をエージェントスキルに変換する方法

PDF、EPUB、DOCX、社内文書を、必要な章だけ読み込むエージェントスキルへ変換します。インストール、トークン予算、ヘッドレス実行、MITライセンスを解説します。

技術書をエージェントスキルに変換すると得られるもの

技術書をエージェントスキルに変換するには、PDF、EPUB、DOCX のエクスポート、またはすでに所有している社内文書のフォルダーをコンバーターに指定します。コンバーターはスキルディレクトリを書き出します。そこには、名前付きフレームワークと章のインデックスを含むエントリーファイルと、質問に必要な場合だけエージェントが読み込む章ごとのファイルが含まれます。書籍全体がコンテキストウィンドウに入ることはありません。インデックスは入ります。

これは、エージェントスキルをゼロから作成する作業とは逆です。後者では、すでに把握している手順を記述します。ここでは知識が存在するのに、誰もアクセスできない状態です。例えば、800 ページのベンダー PDF や、執筆者が退職してから開かれていないハンドブックが該当します。必要なのは圧縮とインデックス作成です。skill という言葉に馴染みがなければ、先にエージェントスキルとは何かを読んでください。

ここで使用するコンバーターは、book-to-skill です。これは MIT ライセンスのスキルで、自分のマシン上で実行できます。2026 年 10 月時点の最新タグは v1.4.0 です。重要なのはツール自体よりも、ツールが生成する構造です。FAQ の前にある最後のセクションでは、同じ構造を手作業で構築する方法を説明します。

トークン予算が設計全体を決める理由

コンテキストウィンドウに貼り付けた書籍は、それを必要とするすべての会話で全体のサイズ分のコストが発生します。スキルでは、エントリーファイルを 1 回読み込むコストに加え、質問が実際に参照する章だけがコストになります。このプロジェクトでは、生成する各ファイルに予算を設定しています。

グラフDocumented token budget per generated file, book-to-skill v1.4.0
このグラフのデータ
[
  {
    "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 に converter をリリース固定でインストールする

この skill は git repository です。使用する agent の skills directory に clone します。directory 名が slash command になるため、clone path は任意ではありません。

git clone --depth 1 --branch v1.4.0 \
  https://github.com/virgiliojr94/book-to-skill.git \
  ~/.claude/skills/book-to-skill

--branch は tag を受け取るため、v1.4.0 を checkout し、それより後の内容は取得しません。skill は agent が従う命令の集合です。命令がレビューされないまま変更されると、サーバー上で実行される内容も変わるため、リリースを固定してください。GitHub Copilot CLI は代わりに ~/.copilot/skills/ を読み込み、Amp は ~/.agents/skills/ を読み込みます。

1 行でインストールする npx skills add virgiliojr94/book-to-skill もあります。これは現在の内容を取得します。tool を試す場合に使用してください。再実行する処理には、リリースを固定した clone を使用します。

次に、このサーバーにある extractor を確認します。

cd ~/.claude/skills/book-to-skill
python3 scripts/extract.py --check

--check はインストール済みの extractor を表示します。不足しているものについては、インストール方法も表示します。不足している Python package については、1 つにまとめた pip command を表示します。不足している各 system tool については、ヒントを表示します。この package には Python 3.9 以降が必要です。

clone 後に autocomplete で /book-to-skill が表示されない場合は、/reload-skills を実行するか、agent を再起動します。Claude Code は session 開始時点で存在していた skill directory を監視します。そのため、2 分前に作成した ~/.claude/skills/ はまだ監視対象になっていません。

必要な抽出器はどれか

Python 以外は必須ではありません。どの形式にも標準ライブラリによるフォールバックがあるためです。ただし、フォールバックは性能が劣ります。小規模なサーバーでは、使わない抽出器のインストールに時間を使うことになります。

  • 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 の抽出器を使う場合は、仮想環境を作成し、その中からエージェントを起動します。これにより、スキルが呼び出す 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

固定した v1.4.0 のチェックアウトでは、追加機能として pdf、epub、docx、rtf、technical、all が宣言されています。ここで technical は docling です。プロジェクトのインストールページには、GitHub から直接スタンドアロンのコマンドライン版をインストールする方法 pip install "book-to-skill[pdf,epub,docx] @ git+https://github.com/virgiliojr94/book-to-skill.git" も記載されています。その後、book-to-skill --check でインストール済みの抽出器を一覧表示できます。この方法では PyPI のリリースは不要ですが、v1.4.0 ではなくプロジェクトのデフォルトブランチがインストールされます。また、取得できるのは抽出器のコマンドだけで、/book-to-skill スキルは含まれません。バージョンを固定する場合は、前述のように自分のチェックアウトからインストールしてください。単独の pip install book-to-skill は機能しません。2026 年 10 月時点で、その名前は PyPI に公開されていないためです。

docling は、書籍で必要になるまでインストールしないでください。機械学習スタックを取り込むため、小規模なプランではインストール前に空きディスク容量を確認してください。

ドキュメントのフォルダーに対して、ヘッドレス実行も行う

このコマンドでは、ファイル、フォルダー、引用符で囲んだ glob、または複数のパスを指定できます。その後に、任意でスキル名を指定します。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-research

glob は引用符で囲んでください。これにより、スキルが認識する前に shell が展開するのを防げます。既存のスキルディレクトリをコマンドに指定すると、別のスキルを作成せず、そのスキルに新しいソースが追加されます。

対話的に実行すると、質問が表示されます。対象が技術資料か、テキスト中心の資料かを指定します。これは使用する extractor を決めます。スキルで何を支援させるかも指定します。これにより、参照の深さまたは学習の深さと、それに応じた章ごとの予算が決まります。スキル名も指定します。skills root がまだ存在しない場合、または複数ある場合は、配置先の root も指定します。生成前にはトークン数と所要時間の見積もりが表示され、確認を待ちます。

ヘッドレス実行では、これらの質問に答える人がいません。ユーザーが呼び出せるスキルは 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 配下の一時作業ディレクトリにまとめます。実行の最後に、このディレクトリは削除されます。抽出に失敗したソースはスキップされるため、バッチ全体は継続します。そのため、指定したファイル数より少ないファイルを読み取った状態でも、実行が成功する場合があります。最終レポートのファイル一覧を、フォルダー内の内容と比較してください。章が欠落している場合、通常はソースが欠落しています。

エージェントに渡しても問題のないサーバーで実行してください。権限に関する説明は、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 に登録してはいけません。
  • 原典が自分の著作物である場合、または再頒布を許可するオープンライセンスである場合に公開してください。たとえば、チームが作成したドキュメントや、条件上再頒布が認められている標準規格です。

このツールは、この前提で設計されています。書籍の内容は含まれず、抽出処理はローカルで実行されます。固定された v1.4.0 は任意の gh skill publish 行を表示するだけで、公開範囲を尋ねることはありません。そのため、そこでの判断は完全に利用者に委ねられます。その後、プロジェクトの default branch には、リポジトリの公開範囲を別の1語の質問で尋ねる publish step が追加されました。回答が単独の public という語の場合にのみ public repository を作成し、それ以外の回答では private になります。この step をライセンス上の判断として扱ってください。実際に、それがライセンス上の判断だからです。

社内ハンドブックには、もう1つ問題があります。誰もが認めたがらないほど、認証情報が含まれていることが多いからです。コンバーターを使うと、誰も開かない PDF が、エージェントが必要に応じて読み取るファイルに変わります。生成されたファイルは、commit する前に一度読んで確認してください。あわせて AI エージェントから秘密情報を排除する も参照してください。

1 回の変換にかかる費用は?

以下の数値は、私たちが測定したものではなく、プロジェクトが公開している独自の測定結果です。

グラフCost to convert one full-length book, as published by the project
このグラフのデータ
[
  {
    "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 米ドルでした。Pro Git は 1.23 です。これらの数値は Claude Sonnet 4.5 で測定されました。トークン数は tiktoken を使用して cl100k_base から取得し、2026 年 10 月時点のプロジェクトの docs/performance.md で公開されています。実際の費用は、使用するモデルと料金によって変わります。

このプロジェクトでは、スキルから 1 つの質問に回答する場合、書籍全体をコンテキストに貼り付ける場合と比べて、使用するトークンが 24 ~ 51 倍少なくなることも記録しています。これは保証値ではなく、節約量の傾向として捉えてください。書籍と質問の内容によって変わるためです。ただし、構造上のポイントは変わりません。変換費用は 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 などの明示的な見出しと、その言語ごとの表記を探します。また、Chapter IV や IV. Title などのローマ数字も認識します。番号のないセクションタイトルだけを使う本では、分割結果が不正確になります。その場合は、推測に任せず、章の開始位置を実行時に指定してください。

コマンドが存在しない。 オートコンプリートに /book-to-skill が表示されない場合は、セッション開始後に skills ディレクトリが作成されています。/reload-skills を実行するか、agent を再起動してください。

Docling の処理に時間がかかりすぎる。 1 ページあたり約 1.5 秒かかるため、長い本では CPU 処理に数分かかります。共有サーバーでは、その処理がほかのホストサービスとリソースを競合します。実行時にコンテンツタイプを尋ねられたら text-heavy と回答するか、scripts/extract.py を自分で実行する場合は --mode text を渡してください。Docling を選択する回答は --mode technical です。

ソースが何も表示されずに消える。 読み取れないファイルは、バッチ処理を完了できるようにスキップされます。そのため、実行結果は、渡したソース数より少ないソースについて成功したと報告する場合があります。この事実を確認できるのは、最終レポートのファイルインベントリだけです。完了した実行結果を、実際に渡した内容と照合する習慣は、このツール以外でも役立ちます。unlazy skill の Depth Tree メソッドを使えば、agent が同じ基準で処理結果を確認し、早い段階で作業完了と判断することを防げます。

手作業で同じパターンを適用する

このツールは作業を簡便にするためのものです。転用できるのは構造であり、所有している参考資料であれば、テキストエディターでも同じ構造を作成できます。

  1. エントリーファイルを1つ作成し、コンバーターが対象とする4,000トークン前後に収めます。そこには、指定された概念を正確な表現で記載します。さらに、すべての詳細ファイルと、各ファイルに含まれるトピックを列挙したインデックスを追加します。
  2. 資料をおおよそ1,000トークンずつのファイルに分割します。各ファイルは1つのトピックだけを扱い、ファイル名だけで内容が分かる名前を付けます。
  3. エントリーファイルから、それらの各ファイルについて説明します。説明は、そのファイルを読む条件を示す文の中に記載します。

多くの人が省略するのがこの Step 3 ですが、この手順がパターンを機能させます。エージェントはインデックスを読んで開くファイルを選択します。そのため、インデックスに記載されていないファイルをエージェントが開くことはありません。インデックスが成果物であり、章ファイルは格納場所です。

エントリーファイルを圧縮後の予算内に収めれば、長時間のセッションでも構造全体を維持できます。コンバーターがファイルを作成した場合でも、あなたが作成した場合でも、このルールは変わりません。

FAQ

購入した書籍から作成した skill を公開できますか?

その書籍のライセンスが再配布を許可していない限り、公開できません。converter に適用される MIT license は converter のコードを対象とするもので、入力した資料は対象外です。生成された skill は、その書籍の二次的著作物にあたります。自分のマシン上の ~/.claude/skills/ に保存してください。自分で作成したドキュメントや、オープンライセンスのソースであれば公開できます。固定された v1.4.0 は公開範囲を尋ねませんが、プロジェクトの default branch では現在、独立した質問として公開範囲を尋ね、単独の public の場合だけ公開されます。いずれにしても、この判断は意図的に行う必要があります。

docling は必要ですか。それとも pdftotext で十分ですか?

poppler-utils の pdftotext で、文章の抽出には十分であり、ほぼ瞬時に完了します。書籍の価値が表やコードリストにある場合は docling をインストールしてください。通常のテキスト抽出では、まさにそれらが失われるためです。代わりに速度が低下します。プロジェクトの測定では docling は 1 ページあたり約 1.5 秒かかるため、300 ページのマニュアルでは VPS 上で CPU 処理に数分かかります。

VPS で externally-managed-environment が表示されて pip が失敗するのはなぜですか?

Ubuntu 24.04 と現行の Debian では、system Python が apt によって管理されていると示されます。そのため pip は system Python へのインストールを拒否し、error: externally-managed-environment を出力します。python3 -m venv ~/.venvs/book-to-skill で virtual environment を作成し、それを有効化して、extractor をその環境にインストールしてください。その後、同じ shell から agent を起動します。skill は python3 を呼び出すため、PATH 上にある interpreter が使用されます。この時点では、virtual environment 内の interpreter が使用されます。

生成した skill が slash command として表示されないのはなぜですか?

原因は 2 つあります。command 名は directory 名から決まるため、skill は ~/.claude/skills/<name>/SKILL.md または .claude/skills/<name>/SKILL.md に配置し、SKILL.md と正確に記述する必要があります。path が正しければ、/reload-skills を実行するか、agent を再起動してください。Claude Code は、すでに監視している skill directory 内の編集を検出します。ただし、session の開始後に作成した skills directory は、その操作を行うまで監視されません。

この記事は役に立ちましたか?