Convert-Pdf-To-Md

# Convert PDF to Markdown

When to use this skill

Trigger this skill any time there is a `.pdf` file that needs to be

understood or processed — for example, a user attaches a PDF and asks

questions about it, wants a summary, wants specific data or tables pulled

out, or wants multiple PDFs in a folder processed together. PDF is a

layout/print format, not reliably readable as plain text, so always convert

it to Markdown first using the script in this skill rather than trying to

open or parse the file directly.

This skill only supports `.pdf` — that's MarkItDown's only PDF-family

format, so there's no legacy format to worry about here (unlike Word's

`.doc` or Excel's `.xls`).

**Mixed file types:** When the user references a folder or set of documents

containing multiple supported file types (`.pdf`, `.docx`, `.xlsx`), this

skill handles only `.pdf` files. The agent MUST also invoke the sibling

skills in parallel:

- `convert-word-to-md` for any `.docx` files

- `convert-excel-to-md` for any `.xlsx` files

Never process a folder and silently skip a supported file type. All three

skills must be invoked together when mixed types are present.

Setup (once per environment)

Before the first conversion in a given environment, follow

[`references/setup.md`](references/setup.md) step by step to ensure Python,

pip, `markitdown`, and `pymupdf` (for image extraction) are installed. Do

this proactively rather than guessing whether the environment is ready — the

script itself will also fail with a clear pointer back to that file if a

dependency turns out to be missing, so it's safe to just try the conversion

first if you're reasonably confident setup was already done.

Usage

The conversion script lives at `scripts/convert_pdf_to_md.py`.

**Output structure:** MarkItDown's PDF converter extracts text and tables

only — it has no concept of embedded images at all. This script separately

extracts real embedded images via PyMuPDF and writes a self-contained folder

per document:

<name>/
    img/
        page001_img001.<ext>
        page002_img001.<ext>
        ...
    <name>.md

Because MarkItDown's PDF text does not preserve reliable per-page markers,

there's no safe way to know exactly where inline an image belongs. Rather

than risk misplacing images next to the wrong paragraph, the script appends

a `## Extracted Images` section at the end of the Markdown, with a

`### Page N` subheading per page that has images — read this section

separately from the main body text. If the document has no embedded images,

no `img/` folder or `Extracted Images` section is created.

**Single file:**

python scripts\convert_pdf_to_md.py "C:\path\to\document.pdf"

This creates a `document\` folder next to the source file (containing

`document.md` and, if present, `document\img\`). To control the destination

folder explicitly:

python scripts\convert_pdf_to_md.py "C:\path\to\document.pdf" -o "C:\path\to\output_folder"

**A folder of PDFs (batch mode):**

python scripts\convert_pdf_to_md.py "C:\path\to\folder"

Add `--recursive` to also include subfolders:

python scripts\convert_pdf_to_md.py "C:\path\to\folder" --recursive

Each `.pdf` found gets its own `<name>\` output folder next to it by

default. Pass `-o "C:\path\to\output_parent"` to collect all the generated

`<name>\` folders under a separate parent directory instead (subfolder

structure is preserved when combined with `--recursive`).

After conversion, read the resulting `.md` file(s) to perform the actual

analysis the user asked for — the script's job is only to produce accurate

Markdown (and images), not to interpret the content.

Deciding where output goes

**Default — always output next to the source file.** The `<name>/` folder

is created in the same directory as the source `.pdf`. This is the required

default for every case. Do NOT override it unless the user explicitly asks

for a different location.

**Only us