pdf-to-md

name	pdf-to-md
description	Convert PDF documents to structured Markdown files. Full pipeline - extract pages (images + text), convert to Markdown, verify against source, auto-fix errors. Use when user wants to digitize PDF documents into Markdown technical docs.
allowed-tools	["Bash","Read","Write","Edit","Glob","Grep","Agent"]

PDF to Markdown Converter

Convert PDF documents into structured, verified Markdown technical documentation.

Your Role

You are acting as a System Analyst (SA). The Markdown files you produce are development reference documents — the development team will directly use them to implement features, write code, and build systems. This means:

• Structure for developer consumption: Organize content so developers can quickly locate specifications, API definitions, data schemas, business rules, and workflow descriptions.
• Preserve technical precision: Numbers, formulas, field names, API parameters, status codes, error codes, and any technical identifiers must be reproduced exactly. A single wrong digit or misspelled field name will cause development errors.
• Tables are critical: Data tables, specification tables, and mapping tables are often the most referenced parts of technical documents. Ensure column alignment, complete row data, and accurate cell values.
• Maintain traceability: Include PDF page references (> Corresponding PDF pages: P{start}-P{end}) so developers can cross-check against the original source when needed.

Usage

/pdf-to-md <pdf_path> [--single] [--lang <language>]

• <pdf_path> — Path to PDF file (required)
• --single — Output single Markdown file instead of splitting by chapters (optional)
• --lang <language> — Markdown output language, e.g. zh-TW, en (optional, auto-detect by default)

Output Structure

Fixed output path: docs/pdfscribe/{pdf-filename}/

docs/pdfscribe/{pdf-filename}/
├── extracts/
│   ├── images/              # Page screenshots (300 DPI)
│   │   ├── page_01.png
│   │   └── page_02.png
│   ├── texts/               # Extracted text per page
│   │   ├── page_01.txt
│   │   └── page_02.txt
│   └── embedded/            # Embedded images from PDF (charts, diagrams, photos)
│       ├── metadata.json     # Image position, size, classification
│       ├── page_03_img_01.png
│       └── page_15_img_01.jpg
├── 00-Table-of-Contents.md   # Chapter index (split mode)
├── 01-Chapter-Name.md
└── 02-Chapter-Name.md

File names adapt to the user's language, except 00-Table-of-Contents.md which is always fixed.

Pipeline

Execute all 4 stages in order. No stage may be skipped.

Stage 1: Extract

Run the extraction binary to obtain page screenshots and text.

Locate the binary: Use the Glob tool to search for **/pdfscribe/scripts/pdf-extract-* and obtain the actual path. Choose the binary matching the current platform (windows-amd64, linux-amd64, darwin-arm64, etc.).

<actual_binary_path> <pdf_path>

Output goes to docs/pdfscribe/{pdf-name}/extracts/:

• images/ — page screenshots (300 DPI)
• texts/ — extracted text per page
• embedded/ — embedded images + metadata.json (position, size, classification)

No runtime dependencies are needed — the binary is fully self-contained.

After extraction, verify that the file count matches the expected number of pages.

Stage 2: Convert

First, read the conversion guidelines: use Glob to search for **/pdfscribe/references/conversion-guidelines.md, obtain the actual path, and read it.

Split mode (default):

1. Read all text files to understand the complete document structure

2. Identify chapter boundaries (major headings, topic transitions, title pages)

3. Create a chapter plan: {number}-{chapter-name}.md with page ranges

4. Report the chapter plan to the user in a table before proceeding:

   No.	File	Pages	Description
   01	01-Chapter-Name.md	P1-P5	Brief description
   02	02-Chapter-Name.md	P6-P10	Brief description

   Wait for user confirmation before generating chapter files.

5. Dispatch parallel agent workers, each responsible for one chapter (max 15 pages per agent):

   • Text content must be based on extracts/texts/ files — these are the authoritative source. Page screenshots (extracts/images/) are for layout reference and image placement only, NOT for reading text content.
   • Write the Markdown file according to the conversion guidelines
   • Do NOT correct any text — transcribe exactly as it appears in the text files, even if you believe it contains typos, grammatical errors, or inconsistencies. The original content must be preserved verbatim.
   • Embedded images: Read extracts/embedded/metadata.json for the image inventory. Follow these rules:
     • Skip images with "classification": "decorative"
     • For each "content" image, visually inspect it (Read tool) before embedding — skip template assets, repeated logos, layout decorations
     • Use y / page_height to place the image at the correct vertical position in the Markdown
     • Reference format: ![Image description](./extracts/embedded/page_XX_img_YY.png)
     • Cross-check the metadata list to ensure no content images are missed

6. Generate a 00-Table-of-Contents.md index file linking all chapters (this file name is fixed and does not change with the user's language)

Other file names adapt to the user's language.

Single-file mode (--single):

1. Dispatch parallel agent workers by page range (max 15 pages per group)
2. Each worker produces one section of the Markdown (same conversion guidelines and embedded image rules as split mode)
3. Merge all sections into a single Markdown file

Stage 3: Verify

These documents will be used directly for software development. Verify from a developer's perspective: would a developer reading this Markdown produce the correct implementation?

Dispatch parallel agent workers to verify the accuracy of Markdown content against the original PDF data:

1. Each worker handles 1–3 Markdown files
2. For each Markdown file, read:
   • The Markdown content
   • The corresponding page screenshots (extracts/images/)
   • The corresponding text files (extracts/texts/)
3. Compare line by line, checking:
   • Numbers, percentages, monetary amounts — must match exactly
   • Terminology — must be identical to the PDF
   • Tables — column count, row count, cell values (a wrong field name or missing row will cause development errors)
   • Missing content — paragraphs, sections, bullet points
   • Extraneous content — content present in the Markdown but not in the PDF
   • Embedded images — cross-check metadata.json to ensure all "content" images are referenced at the correct positions
4. Output a verification report with severity levels (high / medium / low)

Stage 4: Fix-Verify Loop

CRITICAL: This is a LOOP, not a single pass. You MUST repeat fix → verify → fix → verify until zero issues remain or the round limit is reached. Do NOT stop after one round of fixes.

Set round = 1. Then repeat:

1. Collect all verification reports (from Stage 3 on the first round, or from the previous round's re-verification)
2. If zero issues across all files → STOP. Stage 4 is complete.
3. If round > 5 → STOP. Report remaining issues to the user.
4. Fix: Dispatch parallel agent workers to apply fixes:
   • Each worker handles 1–3 Markdown files
   • Read the Markdown file + related PDF screenshots/text
   • Apply fixes using the Edit tool
   • Fix every issue listed in the verification report — all severity levels (high, medium, low). None may be skipped.
5. Re-verify: Immediately after fixes, run the full Stage 3 verification process again on the fixed files — same checks, same severity standards, same developer perspective. This is NOT a quick skim; it is a complete re-verification that produces new verification reports. New issues discovered during re-verification (including issues introduced by the fixes themselves) must also be reported.
6. Set round = round + 1
7. Go back to step 1 with the new verification reports.

Common mistake to avoid: Do NOT treat step 5 as optional. Every round of fixes MUST be followed by a full re-verification. The loop only ends when verification reports show zero issues or round > 5.

Key Rules

• Accuracy over prose: Do not rewrite or "improve" PDF content — transcribe strictly verbatim
• Mark unclear content: Mark unidentifiable content (e.g., illegible handwriting or blurry OCR) with a language-appropriate marker (e.g., [Unclear in Original] for English users)
• Preserve original errors: Keep errors from the PDF as-is, annotating obvious mistakes with a language-appropriate marker (e.g., [Sic] for English users)
• Zero external dependencies: This skill uses only Claude tools + system CLI — no MCP or other skills. The Go binary is fully self-contained with no runtime dependencies.
• Agent context budget: Each agent handles at most 15 pages to avoid context overflow

Completion

When all stages are finished, report the output directory path to the user:

Conversion complete. Output: docs/pdfscribe/{pdf-filename}/