プログラミング書をAI Agentの専門スキルに変える方法

PDFを読み込ませたのに、コードの前提条件やページ番号が消え、AI Agentがもっともらしい誤答を返していませんか。

今週は、PDF解析、Knowledge Base、Agent Skillを分離する三段構成に切り替えてください。Knowledge Baseには検索可能な事実と出典を残し、Skillにはタスクの手順とツール呼び出しだけを定義する方法が最も保守しやすいです。

この方法を使うべき人

コード、表、スキャンページを含む合法的なプログラミング書を処理したい人向けです。全文をSkillへ埋め込む方法と、Knowledge Baseから必要な箇所だけ検索する方法を比較しているAgent開発者にも適しています。

複数の書籍をチームで更新し、版の違い、実行環境、引用元まで管理したい場合は、最初から三層構成にしてください。

まずPDFを3種類に分けて判定する

PDFをいきなりOCRへ送ると、処理時間だけでなく文字順序の乱れも増えます。最初にページ単位で、テキスト層の有無、画像比率、段組み、表、コードブロックを確認します。

PDFの状態	推奨する入口	Knowledge化の注意	Agent Skillへの適性	評価
テキスト型	通常抽出＋ブロック情報	ページ、章、座標を保持	手順だけを参照させる	5/5
スキャン型	必要ページだけOCR	認識結果を原ページと照合	コード実行前に人手確認	3/5
表や段組みが多い型	レイアウト解析	表、列順、見出しを個別検査	直接埋め込みは避ける	3/5
コード密集型	説明・コード・環境を連結	版、依存関係、期待結果を保存	検証手順に変換しやすい	4/5

ここでの評価は機能の優劣ではなく、再利用時に出典と実行条件を維持しやすいかという観点です。

第一段階：テキスト型PDFはページ情報を残して抽出する

テキスト型PDFでは、単純な全文テキストよりも、段落やコードブロックの位置を保持できる形式を選びます。PyMuPDFは通常のテキスト抽出に加え、ブロック、単語、辞書形式などを取得できます。sort=Trueによる左上から右下への並べ替えも可能ですが、PDFの作成方法によって自然な読順にならない場合があります。［PyMuPDFのテキスト抽出仕様］(https://pymupdf.readthedocs.io/en/latest/app1.html) (pymupdf.readthedocs.io)

抽出時に保存する最低限の情報は、書名、版、章見出し、PDF上のページ、本文のページ、ブロック種別、コード言語です。ページ番号を削ると、Agentが回答を引用できず、利用者が原文を確認できません。

次に、ヘッダー、フッター、柱、ページ番号、文字化けを検査します。特に2段組みでは、左列の途中に右列が割り込むことがあります。抽出結果だけを信用せず、代表ページを原PDFと見比べてください。

注意：利用権限のないPDFを取り込んだり、暗号化や著作権保護を回避したりする手順は扱いません。処理対象は、あなたの組織が合法的に利用できる資料に限定してください。

第二段階：スキャン版は必要なページだけOCRする

スキャン版プログラミング書では、まず検索可能な文字が存在するページを判定します。全ページを一律にOCRするのではなく、文字抽出が空になるページ、画像で覆われたページ、コードや表が画像化されたページを優先します。

PyMuPDFの公式資料では、OCRは通常のテキスト抽出より約1000倍遅いと説明されています。そのため、OCR結果をページごとに保存し、同じページへ何度もOCRを実行しない設計が重要です。［PyMuPDFのOCR手順］(https://pymupdf.readthedocs.io/en/latest/recipes-ocr.html) (pymupdf.readthedocs.io)

スキャン版からコードを抽出する場合は、次の順で確認します。

インデントが連続しているか
0、O、1、lなどが入れ替わっていないか
記号、括弧、アンダースコアが欠落していないか
行番号やページ端のノイズが混入していないか
コードの直前にある依存関係と実行コマンドが残っているか

表や複雑なレイアウトを扱う場合、UnstructuredはPDFに対してfast、hi_res、ocr_onlyなどの処理戦略を用意しています。表構造を取得したい場合は、公式例でもhi_resと表推定を組み合わせています。［UnstructuredのPDF分割仕様］(https://docs.unstructured.io/open-source/core-functionality/partitioning)・［表抽出の公式例］(https://docs.unstructured.io/examplecode/codesamples/apioss/table-extraction-from-pdf) (docs.unstructured.io)

第三段階：コードを「実行可能な知識単位」にする

コードだけをKnowledge Baseへ保存する設計は危険です。AI Agentが断片コードを見つけても、必要なライブラリ、対応バージョン、入力形式、期待結果が分からなければ実行できません。

1つの知識単位には、少なくとも次の項目をまとめます。

目的：何を実現するコードか
前提：OS、言語、フレームワーク、依存パッケージ
入力：ファイル形式、引数、環境変数
本文：説明とコード
実行方法：コマンド、作業ディレクトリ
期待結果：出力例、終了条件、既知の失敗
出典：書名、章、ページ、版

コードと解説が別々のチャンクになると、検索結果が片方だけ返ることがあります。章見出し、直前の説明、コード、直後の結果を同じ意味単位として扱う方が、質問への回答と実行検証をつなげやすくなります。

第四段階：Knowledge BaseとSkillの役割を分ける

Knowledge Baseは「何が書かれているか」を保存する場所です。Agent Skillは「どの条件で起動し、何を確認し、どの順で作業するか」を定義する場所です。

LlamaIndexのノード分割では、文書を意味的に関連する単位へ分割し、メタデータをノードへ引き継ぐ設計が可能です。固定文字数だけで区切るのではなく、章、手順、コード例、エラー説明の境界を優先してください。［LlamaIndexの意味分割ドキュメント］(https://docs.llamaindex.ai/en/stable/api_reference/node_parsers/semantic_splitter/) (docs.llamaindex.ai)

PDFをそのままAgent Skillに入れるべきか

短く、内容が安定し、特定の作業だけに使う資料なら、Skill内の参照資料として一部を置く方法もあります。しかし、書籍全文や版違いの大きな資料をSKILL.mdへ詰め込む方法は避けてください。

Agent Skillsの仕様では、必須ファイルはSKILL.mdで、詳細資料はreferences/へ分離できます。Skillはメタデータで発見され、起動時に手順を読み、必要に応じて参照資料を読み込む段階的な仕組みです。仕様上、nameは64文字以内、descriptionは1024文字以内で、本文は500行未満が推奨されています。［Agent Skills仕様］(https://agentskills.io/specification)・［Agent Skillsの概要］(https://agentskills.io/home) (agentskills.io)

したがって、Skillには次の内容だけを置きます。

起動条件
検索すべき章やタグ
引用を必須にするルール
コードを実行する順序
結果の確認方法
不一致や出典不足があった場合の停止条件

書籍の本文、長いコード例、版ごとの差分はKnowledge Baseまたはreferences/で管理します。

第五段階：引用と検索境界を設計する

Knowledge Baseの各単位には、次のメタデータを付けます。

source_title: "書籍名"
edition: "第X版"
chapter: "第Y章"
pdf_page: 123
section: "見出し"
content_type: "explanation|code|table|result"
language: "Python"

検索では「Pythonの非同期処理」のような主題だけでなく、「第X版」「第Y章」「Python 3系」のような条件も利用できるようにします。新旧の版が混在する場合、同じ説明を一つに統合せず、版差分を別の知識単位として保持してください。

回答生成時は、出典がない推測を禁止します。検索結果にページや版が付いていなければ、Agent Skillは回答を続けず、「該当する出典を確認できない」と返す方が安全です。

第六段階：コード実行には隔離と検証を追加する

書籍のコードを実行するSkillでは、検索と実行を同じ権限で扱わないでください。実行前に依存関係、ネットワーク接続、書き込み先、秘密情報へのアクセスを確認します。

最低限、次の検証を分けて実施します。

抽出後のコードと原ページを照合する
依存パッケージと対応バージョンを固定する
一時ディレクトリで実行する
入力データをテスト用に限定する
標準出力、終了コード、生成物を保存する
期待結果と一致しない場合はSkillを成功扱いにしない

ローカル環境に直接実行させると、書籍中の削除コマンド、外部通信、環境変数参照がそのまま動く可能性があります。専用の隔離実行環境を使い、必要な権限だけを許可してください。

多数の書籍を保守する手順

複数の書籍を扱う場合は、書籍ごとに完全分離するのではなく、共通テーマの検索インデックスを作りながら、出典IDは保持します。例えば「HTTP認証」というテーマでまとめても、書籍名、版、章、ページは削除しません。

新しい版を追加したときは、全件を作り直すのではなく、変更された章を特定します。その章に紐づくKnowledge単位、埋め込み、引用テスト、関連Skillだけを更新します。版の違いが実行結果に影響するコードでは、同じ入力を使った再実行テストも必要です。

運用前の判定は次の通りです。

内容が短く、長期的に変わらない：Skill内へ限定的に記載
書籍全文、表、長いコード：Knowledge Baseへ保存
実行手順、引用ルール、停止条件：Agent Skillへ記載
版が複数ある：共通テーマで検索し、版メタデータは分離
スキャンや表が多い：原ページ画像と抽出結果を両方保管

現在の環境とMac環境を比べる

既存のノートPCや共有サーバーで小規模な抽出を行うなら、追加環境は不要です。ただし、OCR、レイアウト解析、ベクトル化、コード検証を同時に走らせると、メモリ競合、実行待ち、依存関係の衝突が起きやすくなります。

一方、毎回異なる端末で処理すると、OCR言語パックやPython環境が揃わず、同じPDFでも結果が変わることがあります。短期の検証やチーム用の再現環境が必要なら、Macをレンタルして解析用と実行用を分ける選択肢があります。利用前にはVPSSparkのサービス概要を確認し、国内拠点を使いたい場合は日本向けMac環境の条件を確認してください。

ただし、長期の固定負荷、物理USB機器、特定GPUへの依存がある場合は、自社所有の端末や専用サーバーの方が適しています。現在の環境で起きている待ち時間、権限分離の難しさ、環境差分を洗い出し、それが一時的な課題ならレンタルMac、恒常的な課題なら専用環境という順で判断してください。

三段構成を採用すれば、PDFの内容をSkillへ無理に詰め込まず、出典を保ったままAgentの実行手順だけを更新できます。今週は合法なテキスト型、スキャン型、コード密集型の3種類を少量ずつ処理し、原ページとの一致、引用の再現、隔離実行の3点を確認してから本格的な書籍移行へ進めてください。