| name | pdf-reading |
| description | Read, summarize, search, and extract structured artifacts from PDF files, especially papers and reports. Use when the user wants a PDF converted before reading, needs figures or tables pulled out, wants image labels or captions, or needs cleaner Markdown/text than reading the PDF directly. |
PDF Reading
Use this skill for PDF-first work on papers and reports. The default path is Docling-first.
Rules
- Never read a PDF directly. Convert it first, then read the generated artifact.
- Default to Docling for reading. Use
--fast only when the user explicitly prefers speed over fidelity.
- Extract figures or tables only when the user asks for them or when the answer depends on them.
- For tables, prefer the cleaned Markdown for quick review, but inspect the crop image when numeric fidelity matters.
- If values or labels look suspicious, cite the crop or page artifact rather than trusting the structured export.
- If Docling fails, fall back to
pdftotext -layout and continue with a degraded-quality warning.
Quick Start
Run the extractor on a PDF:
python3 scripts/pdf_extract.py /path/to/paper.pdf
Extract figures with structural labels:
python3 scripts/pdf_extract.py /path/to/paper.pdf --extract-figures
Extract figures with richer descriptions instead of classifier labels:
python3 scripts/pdf_extract.py /path/to/paper.pdf --extract-figures --figure-label-mode description
Extract tables, agent-facing JSON, LaTeX, cleaned Markdown, CSV, and crop images:
python3 scripts/pdf_extract.py /path/to/paper.pdf --extract-tables
Extract both figures and tables:
python3 scripts/pdf_extract.py /path/to/paper.pdf --extract-figures --extract-tables
Use the faster MarkItDown path only when requested:
python3 scripts/pdf_extract.py /path/to/paper.pdf --fast
Outputs
<basename>.docling.md: primary reading artifact from Docling.- Inline tables inside
<basename>.docling.md now get a compact YAML artifact block immediately after the table with links to the extracted table sidecars.
<basename>.layout.txt: fallback text artifact when Docling fails.<basename>.docling_artifacts/: extracted figure images referenced by Markdown.<basename>.figures.json: figure metadata, labels, captions, and image paths.<basename>.tables/: raw and cleaned table Markdown, CSV exports, and crop images.<basename>.tables/<table_nnn>.raw_docling.json: full Docling table object dump.<basename>.tables/<table_nnn>.agent.json: cell/span AST with provenance, regression semantics, and embedded LaTeX.<basename>.tables/<table_nnn>.html: Docling HTML rendering for the table.<basename>.tables/<table_nnn>.otsl.txt: Docling OTSL table structure dump.<basename>.tables/<table_nnn>.tex: synthesized canonical LaTeX table output.<basename>.tables.json: table metadata, paths, and verification flags.
The script prints a JSON summary with the exact artifact paths to read next.
Maintainer benchmark fixtures and runners live under tests/pdf-reading/ rather than inside the installable skill.
