---
name: pdf-to-md
description: Convert a PDF to one clean markdown file, preserving wrapped tables and rendering diagrams as faithful transcription.
disable-model-invocation: true
---

# PDF → Markdown

Convert a PDF into one clean `.md` by reading each page as an image and transcribing what is on it. Reading pages as images lets a wrapped table cell be seen whole — the way a human sees it — so it unwraps correctly where a layout extractor mangles it.

> A prompt skill — the contract below is tool-agnostic, so it runs the same in Claude Code (`/pdf-to-md`), Cursor, or Copilot Chat.

## Two verbs, one rule

The whole skill hangs on telling these apart:

- **Reconstruct layout** — reading order, line continuation, which column a wrapped fragment belongs to. Allowed; for prose, near-deterministic.
- **Invent content** — words, numbers, labels, arrows, headings not on the page. Forbidden. Mark the gap instead.

> Better to mark a gap than to fill it plausibly.

## Run

1. Read every page as an image.
2. For each page, transcribe into markdown, applying the contracts below.
3. Concatenate pages in order into a single `.md`. Emit at `<pdf-basename>.md` beside the source unless told otherwise.

Completion criterion: every page accounted for; every table a valid markdown table; every diagram either transcribed or explicitly marked untranscribed; zero content that is not on the source page.

**Finish.** Affirm the completion criterion clause by clause before declaring done. If any clause is unmet, continue the work or report the gap explicitly.

## Contracts

### Tables

Preserve the table as a markdown table. Unwrap wrapped cells so each row is one line. When a wrapped fragment's column assignment is near-certain, place it and move on. When it is genuinely ambiguous, place the most-likely column and append `[inferred]` to that cell — making the judgement visible rather than plausible. Never silently guess.

### Diagrams

Faithful transcription + prose, never re-creation:

- Transcribe every readable label, arrow, and caption verbatim.
- Follow with one prose line summarising what connects to what.
- Render structure as transcription, not as Mermaid or ASCII.

### Illegible content

Any text you cannot read clearly (ink too light, overlapping glyphs, diagram too dense), mark inline with `[illegible]` rather than guess.

### Image-dominant pages

When a page is almost entirely an image, photo, or screenshot rather than a textual page, transcribe any visible labels and describe the figure in one line, prefixed `[image page]`. Describe only what is visible; narrate nothing you cannot verify.