How to use the PDF toolkit (pdf-official) agent skill

What the skill makes the agent do

The skill covers any task where a PDF is produced, opened, transformed, filled or read. The source lists extracting text or tables from an existing PDF, combining, carving, rotating, cropping or watermarking pages, composing a fresh PDF such as a report, invoice or certificate, filling AcroForm fields or overlaying text onto a non-fillable scanned form, encrypting or unlocking a PDF, running OCR over a scanned document, and rendering pages to PNG or JPEG for visual analysis.

The agent follows a fixed order for mixed tasks: probe the file, plan, extract or compose, then validate. The first step runs scripts/survey.py, which reports page count, whether the file is locked, the number of form fields, and whether page 1 looks like a scan.

• Probe: page count, encryption, form fields, scan detection
• Extract: text, tables, metadata, images
• Transform: combine, split, rotate, watermark
• Compose: build reports and invoices from data
• Fill: AcroForm widgets or overlay text on non-fillable forms

How do you install the pdf-official skill?

Download the ZIP from this page and unzip it into one of two locations: ~/.claude/skills/ for all your projects, or a project's .claude/skills/ folder for one project. Alternatively, in the Claude apps, open Settings, then Capabilities, then Skills, and upload the skill there.

The skill's own setup section recommends a Python-only install first, which covers most tasks. Add qpdf, Tesseract or Poppler only when you need encryption, OCR or Poppler's command-line tools.

How do you trigger the skill with natural requests?

You do not need to name the skill. The skill triggers on mentions of 'PDF', a filename ending in .pdf, requests such as 'turn this into a PDF report', or references to AcroForm or form fields. Say what you want done to the file, and name the file if you have one.

If the file is locked, the skill routes you to unlock it first. If it is a scan with no selectable text, it routes to OCR, because text extraction returns nothing for scanned pages.

• Turn this invoice data into a PDF with a totals table.
• Extract the tables from report.pdf into CSV.
• Merge these three PDFs and remove page 2 from the second one.
• Fill the name and date fields in form.pdf.
• Rotate the scanned pages in scan.pdf and check the page count.
• Render page 3 of contract.pdf to PNG so I can look at it.

What does the skill need?

The core needs Python 3 and the pip packages pypdf, pdfplumber, pypdfium2, reportlab and Pillow. qpdf is optional and is used for encryption, repair and flattening. Tesseract with pytesseract and pdf2image is optional for OCR. Poppler is optional and is GPL-2.0 at the command-line level.

The source's install commands use Homebrew (macOS) and apt (Debian or Ubuntu). Scripts use argparse, and exit codes are 0 for OK, 1 for runtime failure, 2 for bad arguments and 3 for validation failure in the form-filling scripts. The skill reports that it makes no network calls.

• Required: Python 3, pypdf, pdfplumber, pypdfium2, reportlab, Pillow
• Optional: qpdf, Tesseract with pytesseract and pdf2image, Poppler

Safety notes: scripts, network and signatures

The skill runs scripts, so read them before you trust a run on important files. The source states it does not use the network. Some optional tools and OCR may run locally on the document contents, and the setup commands install third-party software with pip, Homebrew or apt.

The scripts refuse signature fields and do not create certified signatures. Do not use this skill as the basis for legal or signature-critical work. For sensitive documents, avoid sending them to unknown hosts and check what each optional tool does before installing it.

• Scripts run locally; the skill declares no network use.
• Setup installs third-party packages; review the commands first.
• Signature fields are refused; no certified signatures are made.
• XFA forms are not AcroForms and must be flattened in Acrobat first.

Tips for reliable results

Start by asking the agent to run the survey on the file, so you see the flags before any changes. If pypdf returns nothing for a document, check whether it is a scan rather than assuming a bug. Coordinate bugs usually come from PDF's bottom-left origin versus the image's top-left origin.

For new documents with CJK text, the source says a missing font can silently fall back to Helvetica, which has no CJK glyphs, so check the output. For encryption, the source notes pypdf defaults to RC4 and recommends AES-256 for real protection.

• Run the probe first, every time.
• Check the page count and metadata in the probe output.
• Pick AES-256 for encryption rather than the pypdf default.
• Use the bundled runtime if the MIMO_PYTHON environment variable is set; the skill then skips the pip installs.