pdf-to-markdown

PDF から Markdown への変換

PDF の内容をすべて構造化された Markdown として抽出し、次の要素を保持します。

• 見出し（フォントサイズから検出し、# タグに変換）
• 太字、斜体、等幅フォントの書式
• 表（Markdown の表に変換）
• リスト（番号付き、番号なし）
• 複数列のレイアウト（正しい読み取り順）
• コードブロック
• 画像（抽出して出力ファイルの隣に相対パスでコピー）

このスキルを使用する場面

次の場合に使用してください。

• ユーザーがコンテキスト内で「PDF 全体」または「ドキュメント全体」を求めている
• PDF の内容を分析、要約、または議論する
• ユーザーが PDF を「読み込む」「読む」「取り込む」「抽出する」と言っている
• grep や検索ではコンテキストや構造を見落とす可能性がある
• PDF に保持すべき表、書式、または構造がある

環境のセットアップ

このスキルでは、ユーザーの作業ディレクトリを汚さないよう、専用の仮想環境 ~/.claude/skills/pdf-to-markdown/.venv/ を使用します。

初回セットアップ（.venv が存在しない場合）

# For fast mode only (PyMuPDF):
cd ~/.claude/skills/pdf-to-markdown && uv venv .venv && uv pip install --python .venv/bin/python pymupdf pymupdf4llm

# For --docling mode (high-accuracy tables):
cd ~/.claude/skills/pdf-to-markdown && uv venv .venv && uv pip install --python .venv/bin/python pymupdf docling docling-core

# Or install everything:
cd ~/.claude/skills/pdf-to-markdown && uv venv .venv && uv pip install --python .venv/bin/python pymupdf pymupdf4llm docling docling-core

インストールの確認

# Verify fast mode:
~/.claude/skills/pdf-to-markdown/.venv/bin/python -c "import pymupdf; import pymupdf4llm; print('OK')"

# Verify docling mode:
~/.claude/skills/pdf-to-markdown/.venv/bin/python -c "import pymupdf; import docling; import docling_core; print('OK')"

クイックスタート

# Convert PDF to markdown (always extracts images)
~/.claude/skills/pdf-to-markdown/.venv/bin/python ~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py document.pdf

# Output: document.md + images/ folder (next to the .md file)

標準的なワークフロー

ユーザーが PDF を渡し、内容全体をコンテキストに取り込むよう求めた場合：

ステップ 1：スキルの venv が存在することを確認する

test -d ~/.claude/skills/pdf-to-markdown/.venv || (cd ~/.claude/skills/pdf-to-markdown && uv venv .venv && uv pip install --python .venv/bin/python pymupdf pymupdf4llm)

ステップ 2：PDF を Markdown に変換する

~/.claude/skills/pdf-to-markdown/.venv/bin/python ~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py "/path/to/document.pdf"

ステップ 3：出力を読む

# Output is written to document.md in the same directory as the PDF
cat /path/to/document.md

キャッシュ

再処理を避けるため、PDF は積極的にキャッシュされます。最初の抽出には時間がかかりますが、2 回目以降のリクエストは瞬時に完了します。

仕組み

• キャッシュの場所：~/.cache/pdf-to-markdown/<cache_key>/
• キャッシュキー：ファイルの内容のハッシュと抽出モードに基づきます
• 無効化：次の場合にキャッシュは無効になります。
  • ソース PDF が変更された場合（サイズまたは mtime の変更）
  • 抽出ツールのバージョンが変更された場合（自動的に再抽出）
  • --clear-cache または --clear-all-cache で明示的に消去した場合

キャッシュコマンド

# Clear cache for a specific PDF
~/.claude/skills/pdf-to-markdown/.venv/bin/python ~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py document.pdf --clear-cache

# Clear entire cache
~/.claude/skills/pdf-to-markdown/.venv/bin/python ~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py --clear-all-cache

# Show cache statistics
~/.claude/skills/pdf-to-markdown/.venv/bin/python ~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py --cache-stats

キャッシュの内容

~/.cache/pdf-to-markdown/<cache_key>/
├── metadata.json    # source path, mtime, size, total_pages
├── full_output.md   # cached full markdown
└── images/          # extracted images

画像の処理

画像は常に抽出されます。画像は次のように処理されます。

1. ~/.cache/pdf-to-markdown/<cache_key>/images/ にキャッシュされます
2. 出力 .md ファイルの隣にある images/ フォルダーにコピーされます
3. 相対パス（images/filename.png）で Markdown 内から参照されます
4. ドキュメントの末尾の表にまとめられます

画像の自動表示動作

重要： 抽出された Markdown に次のような画像参照が含まれている場合：

**[Image: figure_1.png (1200x800, 125.3KB)]**

ユーザーから、視覚的な要素（チャート、グラフ、図、スクリーンショット、レイアウト、デザイン、プロット、イラスト）に関する質問があったら、回答する前に自動的に Read ツールを使って関連する画像ファイルを確認してください。ユーザーに尋ねず、そのまま確認してください。

画像を自動表示する場面の例：

• ユーザー：「3 ページ目のチャートには何が示されていますか？」→ 画像ファイルを読む
• ユーザー：「この論文の図を要約してください」→ すべての画像ファイルを読む
• ユーザー：「図には何が描かれていますか？」→ 画像ファイルを読む
• ユーザー：「示されているアーキテクチャを説明してください」→ 画像ファイルを読む
• ユーザー：「結果は何ですか？」（結果を示す図がある場合）→ 図を読む

出力形式

Markdown の出力には次の内容が含まれます。

ヘッダー（メタデータ）

---
source: document.pdf
total_pages: 42
extracted_at: 2025-01-15T10:30:00
from_cache: true
images_dir: images
---

画像参照を含むコンテンツ

# Main Title

## Section Header

Regular paragraph text with **bold**, *italic*, and `code` formatting.

![Figure 1](images/figure_1.png)

**[Image: figure_1.png (800x600, 45.2KB)]**

| Column A | Column B |
|----------|----------|
| Data 1   | Data 2   |

画像の概要表（末尾）

---

## Extracted Images

| # | File | Dimensions | Size |
|---|------|------------|------|
| 1 | figure_1.png | 800x600 | 45.2KB |
| 2 | chart_2.png | 1200x800 | 89.1KB |

スクリプトの参照

場所：~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py

Usage: pdf_to_md.py <input.pdf> [output.md] [options]

Options:
  --docling         Use Docling AI for high-accuracy tables (~1 sec/page)
  --no-progress     Disable progress indicator

Cache Options:
  --clear-cache        Clear cache for this PDF and re-extract
  --clear-all-cache    Clear entire cache directory and exit
  --cache-stats        Show cache statistics and exit

高精度モード（Docling）

複雑な表を含み、高精度な処理が必要な PDF には、--docling フラグを使用してください。

~/.claude/skills/pdf-to-markdown/.venv/bin/python \
    ~/.claude/skills/pdf-to-markdown/scripts/pdf_to_md.py \
    document.pdf --docling

--docling を使用する場面：

• PDF に複雑な表（罫線なし、セル結合、複数列）がある
• 表の精度が重要（医療データ、財務レポート）
• デフォルトモードで表の出力が文字化けしている

トレードオフ：

• 1 ページあたり約 1 秒（高速モードでは瞬時）
• 初回実行時に AI モデルをダウンロード（約 500MB、初回のみ）
• より高解像度の画像（デフォルトの 4 倍）

注： --accurate は --docling のエイリアスです。

トラブルシューティング

「No module named pymupdf4llm」と表示される、または venv が存在しない

スキルの仮想環境を再作成してください。

# For fast mode:
cd ~/.claude/skills/pdf-to-markdown && rm -rf .venv && uv venv .venv && uv pip install --python .venv/bin/python pymupdf pymupdf4llm

# For docling mode:
cd ~/.claude/skills/pdf-to-markdown && rm -rf .venv && uv venv .venv && uv pip install --python .venv/bin/python pymupdf docling docling-core

抽出品質が低い

• 複雑な表には --docling を試してください
• スキャンされた PDF の場合、Tesseract OCR がインストールされていることを確認してください：brew install tesseract

表が正しく表示されない場合

複雑な表には、IBM の TableFormer AI モデルを使用する --docling モードを使ってください。

他の方法との比較

方法	使用例	制限事項
このスキル（pymupdf4llm）	画像を含むドキュメント全体のコンテキスト	大きな PDF はコンテキストの上限を超える場合があります
--docling モード	複雑な表、医療・金融関連の PDF	処理が遅い（約 1 秒／ページ）、大きなモデルが必要
PDF の grep	特定のテキストを検索	構造が失われ、画像も取得できません
ページ単位の抽出	対象ページ	手動での作業が必要で、ページをまたぐコンテキストが失われます
PDF に対する Read ツール	クイックプレビュー	書式の保持が限定的です