convert-pdf-to-md

PDF を Markdown に変換

このスキルを使うタイミング

理解や処理が必要な .pdf ファイルがある場合は、いつでもこのスキルを実行してください。たとえば、ユーザーが PDF を添付して内容について質問したり、要約を求めたり、特定のデータや表の抽出を依頼したり、フォルダー内の複数の PDF をまとめて処理するよう求めたりする場合です。PDF はレイアウト／印刷用の形式であり、プレーンテキストとして確実に読み取れるとは限りません。そのため、ファイルを直接開いたり解析したりするのではなく、必ずこのスキルのスクリプトを使って最初に Markdown に変換してください。

このスキルが対応するのは .pdf のみです。MarkItDown が対応する PDF 系形式はこれだけなので、ここでは旧形式について心配する必要はありません（Word の .doc や Excel の .xls とは異なります）。

混在するファイル形式： ユーザーが、複数の対応ファイル形式（.pdf、.docx、.xlsx）を含むフォルダーやドキュメント一式を指定した場合、このスキルが処理するのは .pdf ファイルのみです。エージェントは、該当するスキルも並行して必ず実行してください。

• .docx ファイルには convert-word-to-md
• .xlsx ファイルには convert-excel-to-md

対応しているファイル形式を黙ってスキップしたまま、フォルダーを処理してはいけません。ファイル形式が混在している場合は、3 つすべてのスキルをまとめて実行する必要があります。

セットアップ（環境ごとに 1 回）

ある環境で初めて変換する前に、Python、pip、markitdown、および pymupdf（画像抽出用）がインストールされていることを確認するため、references/setup.md の手順に従ってください。環境が準備できているか推測するのではなく、事前に確認してください。依存関係が不足している場合はスクリプトがこのファイルを参照するよう明確に案内して失敗するため、セットアップが済んでいると確信できる場合は、まず変換を試しても問題ありません。

使い方

変換スクリプトは scripts/convert_pdf_to_md.py にあります。

出力構成： MarkItDown の PDF コンバーターが抽出するのはテキストと表のみです。埋め込み画像を扱う機能はありません。このスクリプトは PyMuPDF を使って実際に埋め込まれている画像を別途抽出し、ドキュメントごとに自己完結したフォルダーを作成します。

<name>/
    img/
        page001_img001.<ext>
        page002_img001.<ext>
        ...
    <name>.md

MarkItDown が抽出する PDF のテキストには、信頼できるページごとのマーカーが保持されないため、画像が本文のどこに配置されていたかを正確に把握する安全な方法はありません。画像を誤った段落の横に配置するリスクを避けるため、スクリプトは Markdown の末尾に ## Extracted Images セクションを追加し、画像があるページごとに ### Page N の小見出しを付けます。このセクションは本文とは分けて読んでください。ドキュメントに埋め込み画像がない場合は、img/ フォルダーも Extracted Images セクションも作成されません。

単一ファイル：

python scripts\convert_pdf_to_md.py "C:\path\to\document.pdf"

これにより、ソースファイルの隣に document\ フォルダーが作成されます（document.md と、画像がある場合は document\img\ が含まれます）。出力先フォルダーを明示的に指定するには、次のようにします。

python scripts\convert_pdf_to_md.py "C:\path\to\document.pdf" -o "C:\path\to\output_folder"

PDF のフォルダー（バッチモード）：

python scripts\convert_pdf_to_md.py "C:\path\to\folder"

サブフォルダーも対象にするには、--recursive を追加します。

python scripts\convert_pdf_to_md.py "C:\path\to\folder" --recursive

見つかった各 .pdf には、デフォルトでそのファイルの隣に <name>\ という出力フォルダーが作成されます。生成された <name>\ フォルダーを別の親フォルダーにまとめるには、-o "C:\path\to\output_parent" を指定します（--recursive と併用すると、サブフォルダーの構造は維持されます）。

変換後、生成された .md ファイルを読み込み、ユーザーが依頼した分析を実行してください。スクリプトの役割は、正確な Markdown（および画像）を生成することだけであり、内容を解釈することではありません。

出力先の決定

デフォルト — 常にソースファイルの隣に出力します。 <name>/ フォルダーは、ソースの .pdf と同じディレクトリに作成されます。これは、すべての場合に必須となるデフォルトです。ユーザーが別の場所を明示的に指定しない限り、変更しないでください。

**-o を使用するのは、**ユーザーが出力先を明示的に指定した場合のみです（例：「出力を C:\output に保存して」「結果を D:\work に置いて」）。エージェントの現在の作業ディレクトリ、セッション状態フォルダー、または暗示されている場所に基づいて -o を指定しないでください。

ソースファイルのパスを完全に特定できない場合 — たとえば、ユーザーがディレクトリを指定せずにファイル名だけを指定した場合や、パスが曖昧な場合 — 変換を実行する前に ask_user を使って、絶対パス全体を確認してください。ディレクトリを推測したり、決めつけたりしないでください。

トラブルシューティング

症状	考えられる原因	対処方法
ModuleNotFoundError: No module named 'markitdown' または 'fitz' ／終了コード 2	MarkItDown または PyMuPDF がインストールされていない	references/setup.md に従ってください
ERROR: Unsupported file type '...' ／終了コード 3	.pdf ファイルではない	ユーザーに正しいファイルを依頼するか、ファイルが .doc／.docx／.xlsx の場合は、対応する別のスキルを使用してください
ERROR: Input path not found ／終了コード 3	パスが間違っている、またはファイルが移動された	ユーザーに正しいパスを確認してください
バッチ出力の FAILED <file> -> ...	該当ファイルが破損している、パスワードで保護されている、またはその他の理由で読み取れない	失敗したファイルを報告してください。バッチ内の他のファイルは引き続き処理されます
NOTE: skipped N non-.pdf file(s)	フォルダーに PDF 以外のファイルが含まれている	想定どおりです — それらのファイルは意図的に無視されます
画像は抽出されているのに、Markdown 本文が空、またはほとんど空	PDF がスキャン画像のみで、埋め込みテキストレイヤーがない。MarkItDown は OCR を実行しません	OCR はサポートされていないことをユーザーに伝えてください。抽出されたページ画像は引き続き表示できます
画像がテキストのインラインではなく、付録に表示される	既知の制限です — MarkItDown の PDF テキストには、画像をインラインに配置するための信頼できるページ単位のマーカーがありません	想定どおりです。必要に応じて、### Page N 見出しと周辺のテキストを相互参照してください