pdf-to-markdown

[IMPORTANT] 作業を開始する前に、TaskCreate を使用してすべての作業を小さなタスクに分割してください。各ファイルの読み取りに関するタスクも含めてください。長いファイルによるコンテキストの喪失を防ぐためです。簡単な作業の場合、AI はスキップしてよいかユーザーに確認しなければなりません。

クイックサマリー

目的： PDF ファイルを、ネイティブテキストとスキャン文書を自動判別しながら、適切に書式設定された Markdown に変換します。現在実装されているのはネイティブテキストの変換のみで、OCR は今後対応予定です。

ワークフロー：

1. 自動判別 — PDF にネイティブテキストが含まれているか、OCR が必要かを判定します
2. 変換 — 入力パスと任意のモード／出力フラグを指定して scripts/convert.cjs を実行します
3. 出力 — 成功ステータス、ページ数、出力パスを含む JSON を返します

主なルール：

• --mode auto（デフォルト）を使用して、ツールにネイティブテキストと OCR のどちらを使うか判断させます
• スキャンされた PDF の OCR には、追加の tesseract.js セットアップが必要です
• 複雑な複数列レイアウトでは、構造が完全に保持されない場合があります

pdf-to-markdown

PDF ファイルを、ネイティブテキストとスキャン文書を自動判別しながら Markdown 形式に変換します。

npm install 不要

このスキルは Node.js のみで実行でき、リポジトリに node_modules はありません。初回使用時に npx で @opendocsg/pdf2md を実行します（npx によってキャッシュされます）。任意で、npx を使わずに高速実行するため、スキルのディレクトリで npm install を実行できます。

要件： Node.js ≥18、npx（npm に含まれています）。

クイックスタート

# Basic conversion (auto-detect native vs scanned)
node .agents/skills/pdf-to-markdown/scripts/convert.cjs --input ./document.pdf

# Specify output path
node .agents/skills/pdf-to-markdown/scripts/convert.cjs -i ./doc.pdf -o ./output.md

# Force native mode (skip OCR detection)
node .agents/skills/pdf-to-markdown/scripts/convert.cjs -i ./doc.pdf --mode native

CLI オプション

オプション	短縮形	説明	デフォルト
--input	-i	入力 PDF ファイルのパス	（必須）
--output	-o	出力 Markdown ファイルのパス	{input}.md
--mode	-m	変換モード：auto、native、ocr	auto
--help	-h	ヘルプメッセージを表示

機能

• 自動判別： PDF にネイティブテキストが含まれているか、OCR が必要かを自動判定します
• ネイティブ PDF： @opendocsg/pdf2md を使用した高速な抽出
• 表： 基本的な表構造を保持します
• クロスプラットフォーム： Windows、macOS、Linux で動作します
• システム依存関係なし： JavaScript のみで実装されています

変換モード

Auto（デフォルト）

最初のページに抽出可能なテキストがあるか確認します。テキストが見つかった場合はネイティブ抽出を使用し、見つからない場合は OCR に関する警告を表示します。

Native

テキストを直接、高速に抽出します。選択可能なテキストを含む PDF（スキャン画像ではないもの）に最適です。

OCR（スキャン PDF）— 近日公開

スキャン文書向けです。現在は実装されていません。PDF がスキャン文書と思われる場合、スキルから通知されます。

出力

成功時は JSON を返します：

{
    "success": true,
    "input": "/path/to/input.pdf",
    "output": "/path/to/output.md",
    "stats": {
        "pages": 5,
        "mode": "native"
    }
}

制限事項

• 複雑な複数列レイアウトでは、構造が保持されない場合があります
• スキャン PDF の OCR 精度は画像の品質によって異なります
• 数式は完全には変換されない場合があります
• 初回の OCR 実行時に言語データ（約 15MB）をダウンロードします

OCR のセットアップ（任意）

OCR モードはスキルに組み込まれていますが、まだ実装されていません。環境を準備する場合や、独自に拡張する場合は、Node が依存関係を解決できるよう OCR の依存パッケージをインストールしてください：

cd .agents/skills/pdf-to-markdown
npm install tesseract.js pdfjs-dist canvas

注： 一部のシステムでは、canvas パッケージのビルドにビルドツールが必要になることがあります。

---

重要なタスク計画に関する注意事項（必ず守ってください）

• 常に作業を計画し、多数の小さな todo タスクに分割してください
• 作業の品質を検証し、修正や改善点を特定するため、必ず最後にレビューの todo タスクを追加してください