# PDF

> Read PDFs locally without OCR or an API key — classify text-based versus scanned in tens of milliseconds and name the pages that still need OCR, convert to markdown with headings, lists and tables intact, and pull positioned text or the exact characters inside a box on a page.

- Skill: `iii-hq/pdf` (Agent Skill)
- Install (CLI): `npx skillmds@latest add iii-hq/pdf`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iii-hq/pdf/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: iii-hq (https://skillmd.com/u/iii-hq)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/iii-hq/pdf

---


# pdf

The pdf worker parses PDF documents on the machine. A PDF is not text: reading
one with a file-reading function returns binary noise and spends the context on
it, so every PDF goes through `pdf::*` instead. Parsing is local, needs no
credential, and sends nothing anywhere.

Its first job is a routing decision. `pdf::classify` samples the document's
content streams and answers whether the pages hold real characters or are
photographs of pages, plus which individual pages cannot be read without a
vision model and why. That verdict decides whether the rest of the work is
worth doing at all, and it is what separates "this document is empty" from
"this document is a scan".

Its second job is reading. Text-based documents convert to markdown that keeps
the shape of the original, because headings, lists and tables are recovered
from font sizes and page geometry rather than from any structure the file
promises. Underneath that sit the positions themselves, for callers that need
to know where text is and not only what it says.

This worker is called on demand. It registers no harness hook and injects
nothing into any prompt, so a conversation that never touches a document never
pays for it. Reach for it when one appears.

## When to Use

- A conversation names a PDF path or hands one over: call `pdf::classify`
  before anything else. Never read a PDF with a file-reading function; it
  returns binary noise and spends the context on it.
- Read a document: `pdf::to-markdown`, narrowed with `pages` when it is long.
- Search or embed a document rather than read it: `pdf::extract-text`.
- Decide whether a document is worth sending to a vision model, and which of
  its pages: `pdf::classify`, then read `pages_needing_ocr` and `ocr_reasons`.
- A vision model located a region and you want the real characters rather than
  its transcription: `pdf::extract-regions`.
- Reason about layout, headings by size, or where a value sits on the page:
  `pdf::extract-items`.

## Boundaries

- Nothing here rasterizes a page, so nothing here can OCR. Scanned and
  image-based documents are classified and routed, never read. Image content
  is reported as a placeholder with a real box and no pixels. `document::ocr`
  is where routed pages go when the `document` worker is installed: it renders
  them and reads them with a vision model, so it costs money per page. Hand it
  the `pages_needing_ocr` this worker named rather than the whole file.
- `suspected_garbled_text` in `ocr_reasons` means the text layer decodes to
  nonsense. Do not trust the extraction, whatever `document_type` says.
- Responses are capped. `truncated: true` with a much larger `total_chars`
  means you hold a fragment and must not answer from it. Narrow with `pages`
  rather than raising the cap: conversion cost scales with the document, so a
  page filter is faster as well as smaller. `max_chars: 0` lifts the cap and
  belongs in a pipeline moving a document to storage, not in a call whose
  result lands in the conversation.
- Encrypted documents take a `password` on `pdf::classify` and
  `pdf::to-markdown` only. The other three cannot decrypt and say so.
- Page numbers are 1-indexed everywhere, in requests and responses.
- Coordinates differ by function and every response states which it used:
  `pdf::extract-items` reports PDF points from the bottom left,
  `pdf::extract-regions` takes boxes in PDF points from the top left. Assuming
  the wrong one returns text from the wrong end of the page with no error.

## Functions

- `pdf::classify` — the routing call. Document type, confidence, page count,
  the 1-indexed pages needing OCR, and a machine-readable reason per page.
- `pdf::to-markdown` — markdown with headings, lists, links and tables
  recovered; optional page filter, per-page output, and a fidelity or compact
  profile.
- `pdf::extract-text` — plain text, no structure recovery. Cheaper than
  markdown when the result will be searched or embedded.
- `pdf::extract-items` — every positioned run of characters with its box,
  font, size, and recovered bold, italic, underline and strikeout.
- `pdf::extract-regions` — the text, or a markdown table, inside given boxes
  on given pages.