PDF Data Extractor

Purpose

Turn data inside a PDF into a structured, reviewable output. The skill is best for text-based PDFs where text can be selected or copied. Scanned PDFs, photos, image-only pages, handwritten forms, or low-quality OCR require OCR or PDF tooling before reliable extraction.

The main deliverable is a data extraction packet:

• Extracted data in CSV, JSON, or Markdown table format.
• Field map that connects requested fields to source pages or sections.
• Data type and normalization notes.
• Exception log for missing, ambiguous, duplicated, or low-confidence values.
• Short extraction summary with assumptions and next steps.

User Scenario

A user has a PDF such as an invoice, bank statement, research report, contract, application form, or operations packet. They need the important rows or fields moved into a clean table or JSON object without losing traceability. They may also need the result prepared for Excel, a database import, a reconciliation task, or a teammate who will verify the data.

Privacy and Fit Check

Before extracting, protect the user and the data.

• Ask whether the PDF contains personal, financial, medical, legal, employee, student, customer, account, tax, or confidential business data.
• Encourage redaction or representative samples when full documents are not needed.
• Do not ask the user to upload sensitive PDFs to external services unless they understand and accept the privacy risk.
• State that this skill does not provide legal, accounting, compliance, or audit certification.
• For scanned PDFs, say clearly that OCR/tool support is required and that extraction confidence may be lower.

Best Inputs

Ask for only what is needed.

• PDF file path, accessible URL, or pasted text/table excerpt.
• Target fields or target table, such as invoice number, vendor, date, subtotal, tax, total, line items, transaction rows, study metrics, or clause names.
• Desired output format: CSV, JSON, Markdown table, or all three.
• Page range or section names when known.
• Locale and formatting rules for dates, currency, decimal separators, account masks, or IDs.
• Whether redaction is required in the final answer.

Install-First Success Path

For the first run after installing the skill:

1. Ask the user for a small, non-sensitive sample PDF or a copied page excerpt if no PDF tool is available.
2. Confirm whether the document is text-based or scanned.
3. Ask for a narrow first extraction target, such as "invoice header fields" or "the first five transaction rows."
4. Return one small structured output plus a field map and exception log.
5. Ask the user to verify two or three source values before expanding to the full document.

Workflow

1. Scope the task. Identify document type, target fields, page range, output format, and downstream use.
2. Check privacy. Flag sensitive categories and recommend redaction, masking, or local-only processing when appropriate.
3. Check document type. Decide whether the PDF appears text-based, scanned, mixed, or unknown. If scanned, require OCR/tool support before claiming reliable extraction.
4. Inspect structure. Identify pages, headers, repeated table regions, footnotes, merged cells, multi-line rows, totals, forms, and page breaks.
5. Build a field map. Define each requested field, source location, expected type, normalization rule, and confidence basis.
6. Extract data. Capture rows or fields exactly first, then normalize into the requested schema.
7. Validate. Check totals, date ranges, duplicate rows, missing required fields, inconsistent currencies, malformed IDs, and row counts.
8. Mark exceptions. Do not silently guess. Log ambiguous, missing, low-confidence, or OCR-dependent values.
9. Deliver outputs. Provide the requested structured data plus summary, field map, exception log, and review checklist.

Output Contract

Return sections in this order unless the user asks for a different format.

1. Extraction Summary

Include document type, pages reviewed, target data, output format, privacy flags, document type confidence, and extraction confidence.

2. Structured Output

Use the requested format. If no format was specified, use Markdown table for small outputs and JSON for nested outputs. For CSV, wrap the result in a fenced csv block.

3. Field Map

4. Exception Log

5. Quality Checks

List the checks performed, such as total reconciliation, row count, required fields present, date format consistency, duplicate detection, and currency consistency.

6. Next Step

Give one concrete next step, such as verify source values, provide page range, run OCR, export to CSV, or expand extraction to all pages.

Sample Prompts

• "Use $pdf-data-extractor to extract invoice number, vendor, invoice date, line items, tax, and total from this PDF into CSV."
• "Use $pdf-data-extractor on /path/to/statement.pdf and return transactions from pages 2-5 as JSON with date, description, amount, balance, and confidence notes."
• "Use $pdf-data-extractor to pull all tables from this research report into Markdown, then flag missing values and weird units."
• "Use $pdf-data-extractor to extract contract parties, effective date, renewal term, payment terms, and termination notice period from this text-based PDF."
• "Use $pdf-data-extractor on this scanned PDF only if OCR is available; otherwise tell me what OCR step is needed first."

Three Real Task Examples

Example 1: Invoice to CSV

Input

• Text-based invoice PDF.
• User asks for vendor, invoice number, dates, line items, tax, and total.
• Desired output: CSV.

Steps

1. Confirm the invoice is text-based and not a scan.
2. Map header fields from page 1.
3. Extract line-item rows from the invoice table.
4. Normalize dates to ISO 8601 and currency to decimal numbers.
5. Reconcile subtotal + tax against total.

Output

vendor,invoice_number,invoice_date,due_date,line_description,quantity,unit_price,line_total,tax,total
Northwind Office Supply,INV-1048,2026-04-30,2026-05-30,Printer paper carton,3,42.00,126.00,11.34,137.34
Northwind Office Supply,INV-1048,2026-04-30,2026-05-30,Toner cartridge,2,88.50,177.00,15.93,192.93

Exception log: none if totals reconcile; otherwise flag the mismatch and source page.

Example 2: Bank Statement Transactions to JSON

Input

• Bank statement PDF, pages 2-4.
• User asks for transaction rows with sensitive account numbers masked.
• Desired output: JSON.

Steps

1. Flag financial data and recommend local-only handling.
2. Mask account numbers except the final four digits.
3. Extract transaction table rows by date order.
4. Normalize debits as negative amounts and credits as positive amounts.
5. Check ending balance against the last transaction row.

Output

{
  "account_mask": "****4321",
  "transactions": [
    {
      "date": "2026-04-03",
      "description": "ACH CREDIT PAYROLL",
      "amount": 2450.00,
      "balance": 3891.20,
      "source": "page 2"
    },
    {
      "date": "2026-04-05",
      "description": "CARD PURCHASE GROCERY",
      "amount": -84.17,
      "balance": 3807.03,
      "source": "page 2"
    }
  ],
  "exceptions": []
}

Example 3: Research Report Table to Markdown

Input

• Text-based PDF research report.
• User asks for all rows in a table comparing tools by accuracy, latency, and cost.
• Desired output: Markdown table plus unit checks.

Steps

1. Locate the requested table and caption.
2. Preserve row labels and column headers.
3. Normalize percentages, milliseconds, and USD cost units.
4. Flag missing values, footnotes, or rows split across pages.
5. Include source page and quality notes.

Output

Exception log: row for Model C continued on page 8; verify footnote marker before publishing.

Clean Scan Evidence

Before marking a result ready, perform and report a clean scan:

• Package scan: list files in the skill directory and confirm no credentials, logs, caches, raw PDFs, private documents, or internal handoff notes are included.
• Language scan: confirm public-facing docs are English-first and contain no large Chinese documentation blocks.
• Sensitive-pattern scan: search for likely credentials, private keys, and account-like sample values.
• Publish-boundary scan: confirm the package does not include publish_queue, release notes, private workspace records, test PDFs, or user data.

Example evidence format:

Files: SKILL.md, agents/openai.yaml
Sensitive scan: no credential-like assignments or private key blocks found
Cache/log scan: no .DS_Store, __pycache__, logs, raw PDFs, or private data files
Language scan: English-first public documentation
Publish status: not published, no publish_queue changes

Safety Boundaries

• Best for text-based PDFs; scanned PDFs require OCR/tool support.
• Do not invent values that are not visible in the source.
• Do not silently repair arithmetic, dates, currencies, or IDs; log corrections as assumptions.
• Do not expose unredacted sensitive data in examples when placeholders or masks will work.
• Do not claim audit-grade, legal, accounting, medical, or compliance validation.
• Do not send private PDFs to external tools unless the user explicitly accepts the privacy risk.