---

name: pdf-extractor version: 0.1.0 description: Extract text, tables, and form-field values from PDF files. Use when the user wants to pull data out of a PDF, fill a PDF form, or convert PDF content to text/markdown.

PDF Extractor

Extract structured content from PDF files.

When to use this skill

Use this when the user asks to:

• Pull text or tables out of a PDF
• Read values from a fillable PDF form
• Convert a PDF to markdown or plain text

Instructions

1. Identify the target PDF path from the user's request.

2. The script depends on pypdf and pdfplumber, which are installed in a venv bundled with this skill. Run the script with the venv interpreter (.venv/bin/python in the skill directory), not the system python. If .venv is missing, create it once with uv:

   uv venv .venv && uv pip install --python .venv -r requirements.txt
   

3. For plain text extraction, run the bundled script:

   .venv/bin/python scripts/extract.py <path-to-pdf> --mode text
   

4. For form fields, use --mode fields. The output is JSON mapping field names to values.

5. For tables, use --mode tables. By default it detects bordered tables via ruled lines. If the table has no borders (columns aligned with whitespace), add --table-strategy text. On a page that mixes prose and a borderless table, also pass --bbox "x0,top,x1,bottom" (PDF points, top-left origin) to crop to just the table — the text strategy otherwise treats the whole page as one table and splits paragraphs into bogus columns. Cross-check column alignment against references/form-fields.md if the layout looks off.

6. If a borderless table's header still mis-splits (wide header words straddle an inferred column edge), pin the columns explicitly with --columns "x0,x1,...,xN" — the boundary x-coordinates including the outer edges. This buckets each word into a column by its center, so headers stay intact. Pair it with --bbox to also bound the rows (otherwise prose above the table gets bucketed in too). To find the coordinates, inspect word positions with pdfplumber's page.extract_words() (each word has x0/x1).

Notes

• If a PDF is scanned (image-only), text extraction will be empty — tell the user it needs OCR, which this skill does not perform.