Index of every page on this site: llms.txt
All skills
paulrberg avatar
by Paul Bergpaulrberg/agent-skills106 stars
11
Run it yourself

Use when PDF files are the primary input or output: read, compare, reconcile, extract text/tables/images, OCR scans, fill forms, split, merge, rotate, rename, compress, or convert between PDF and images. Optimized for private financial, tax, legal, and health documents on macOS.

Use this Skill: https://skilld.dev/gh/paulrberg/agent-skills/pdf

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈71 tokens for metadata: the name and description. ≈1.3k when used: this file. ≈1.9k more on demand in 3 files.

Description uses 3.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈285 characters, or 3.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

PDF

Process PDFs locally on macOS with exact extraction, source preservation, deliberate tool routing, and structural plus semantic validation.

Invariants

  1. Run extraction and transformations locally. Task-relevant document evidence in tool output and internal agent reports may be processed by the configured model provider. Require explicit user authorization and an external-disclosure review before uploading or sending document contents outside that agent workflow. Package and language-data downloads do not authorize document disclosure.
  2. Preserve every original PDF byte-for-byte. Unless the user authorizes destructive replacement, write a sibling output, copy, or explicitly named destination.
  3. Preserve monetary values, identifiers, dates, signs, and displayed precision as strings. Use decimal.Decimal for arithmetic. Never infer missing rows or silently discard headers, footnotes, continuation lines, or boundary pages.
  4. Inspect structure and representative renders before choosing a transformation. Use the smallest tool that preserves the required layout, forms, annotations, and image quality.
  5. Validate every written PDF structurally and against task semantics. A command exiting successfully is not evidence that extracted rows, totals, page boundaries, form appearances, or visual layout are correct.
  6. Keep reports concise for private financial, tax, legal, and health documents. Prefer counts, reconciliations, and file references over raw sensitive rows unless the rows materially support the task or the user asks for them.

Profile First

Resolve the skill directory from this SKILL.md, then profile every unknown input:

uv run "<skill-dir>/scripts/profile.py" "<input.pdf>"

The helper emits schema-versioned JSON with integrity, encryption, page geometry/rotation, image counts, and per-page text coverage without document text. Stop on password_required. Password handling is outside this skill.

When layout, cropping, OCR quality, signatures, or form placement matters, render the first and last page, every structural boundary, and any page behind a discrepancy. For dense charts, tables, or technical drawings, render at higher resolution and crop or zoom the relevant region before reading values.

Route by Evidence

Need Preferred route
Quick reading or page-aware extraction Host PDF reader when available, then pdftotext -layout
Coordinates, columns, or difficult tables Poppler bounding boxes, then pdfplumber through uv run
Image-only or materially incomplete text OCRmyPDF with Tesseract. Default languages: eng+ron
Merge, split, rotate, or integrity checks qpdf
Render pages or extract embedded images pdftocairo or pdfimages
Convert ordered images into a PDF img2pdf
Reduce size qpdf lossless rewrite first. Ghostscript only for an accepted lossy pass
Inspect, fill, flatten, or overlay forms Read references/forms.md first

Only when exact commands for the selected extraction, transformation, OCR, image, comparison, or compression branch are needed, read references/recipes.md.

Execute and Reconcile

  1. Profile inputs and identify whether each page is digital, scanned, mixed, rotated, or image-heavy.
  2. Extract or transform into a new path. For tabular documents, retain page provenance and parse continuations across page breaks before assigning rows.
  3. Reconcile financial and evidentiary output with every available invariant: page and row counts, opening/closing balances, inflows/outflows, subtotals, displayed totals, date coverage, and source hashes when provenance matters.
  4. For comparisons, extract both sources independently, enumerate overlapping and unique facts, and render the pages behind every material disagreement. Distinguish a real discrepancy from an extraction failure.
  5. For split or rename work, establish an old-to-new map from stable content identifiers. Copy by default, preserve contextual boundary pages when needed, and verify the first and last page of every result.
  6. Validate outputs with qpdf, expected page count/dimensions, text coverage, representative renders, and the task's semantic invariants. Retain OCR sidecars or extraction intermediates only when they are requested or useful evidence.

Completion requires preserved originals, intentional outputs, successful structural checks, semantic reconciliation, and a concise report of paths and evidence. Lead read-only reports with ### 📄 PDF — 🔎 inspected, no files written. Only after all required validation passes, use ### 📄 PDF — ✅ updated. When a required check fails, use ### 📄 PDF — ⛔ not deliverable.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts21d3 checks · Risk SAFE
  • Gen Agent Trust Hub21d

    The skill provides a robust set of tools for processing PDF documents locally on macOS. It emphasizes data privacy, document integrity, and systematic validation. No malicious patterns or security risks were identified.

  • Socket23d

    No alerts

  • Snyk23d

    Risk: LOW · No issues

Signed by skilld at c9e5a34. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 days ago.

Activeupdated 2 months ago
argument-hint
[file ...]
Other metadata
compatibility
Requires macOS, uv, Poppler, qpdf, Ghostscript, OCRmyPDF with Tesseract language data, and img2pdf.

README badge

README badge for paulrberg/agent-skills/pdf