pdf-to-markdown

PDF から Markdown への変換

IBM Docling AI を使用して PDF の全内容を構造化された Markdown として抽出し、次の要素を保持します。

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

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

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

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

環境のセットアップ

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

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

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

インストールの確認

~/.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 docling docling-core)

ステップ 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 は積極的にキャッシュされます。初回の抽出には時間がかかります（1 ページあたり約 1 秒）が、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

画像の処理

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

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

画像の自動表示動作

重要： 抽出された 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:
  --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

パフォーマンス

• 初回の抽出：1 ページあたり約 1 秒（Docling AI による処理）
• 初回実行：AI モデルをダウンロードします（一度のみ、約 500MB）
• キャッシュ済みの抽出：即時
• 高解像度画像：鮮明な出力を得るため、デフォルト解像度の 4 倍

トラブルシューティング

「No module named docling」または venv が存在しない

スキルの仮想環境を作り直します。

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

抽出品質が低い

スキャンした PDF の場合は、Tesseract OCR がインストールされていることを確認してください：brew install tesseract

表が正しく整形されない

このスキルでは、複雑な表で約 93.6％ の精度を持つ IBM の TableFormer AI モデルを使用します。それでも表が文字化けする場合は、PDF に特殊な書式が使われている可能性があります。