pdf

name	pdf
description	PDF file inspection, object-level editing, and lossless size reduction using qpdf, pdf-parser.py, pdfsizeopt, and Ghostscript. You MUST load this skill when inspecting, editing, or optimizing PDF files.
license	MIT

PDF Skill

Analyze, edit, and shrink PDF files at the object level without losing content.

WHEN TO USE

• Reducing PDF file size (lossless or lossy)
• Inspecting PDF internals (objects, streams, fonts, metadata)
• Editing or removing specific PDF objects (fonts, images, metadata)
• Diagnosing PDF bloat (duplicate fonts, embedded attachments, large streams)

WHEN NOT TO USE

• For parsing and extracting raw text content for NLP or RAG processing (use standard text extraction tools instead).
• When you need to digitally sign a PDF or apply DRM/encryption, which requires specialized cryptographic libraries.
• For converting HTML/Markdown to PDF (use tools like Pandoc, Puppeteer, or wkhtmltopdf instead).

Common Pitfalls

• Destructive Ghostscript: Running Ghostscript first, which fundamentally rewrites the entire document, destroying the original object structure before you can inspect it.
• Blind Deletion: Deleting an object stream manually in QDF without updating the cross-reference table or checking if other objects depend on it, resulting in a corrupted PDF.
• Ignoring OCR: Reducing image resolution so aggressively that scanned text becomes completely illegible.

Tool Selection

Tool	Install (Ubuntu)	Strength
qpdf	sudo apt install qpdf	Object-level JSON inspection, QDF editing, lossless recompression
pdf-parser.py	wget -O …/pdf-parser.py (Didier Stevens)	Object stats, stream dump, forensic analysis
pdfsizeopt	Single-file Python script (curl)	Best automated lossless reduction (dedup fonts/streams)
Ghostscript (gs)	sudo apt install ghostscript	Fast lossy reduction via presets
mutool (MuPDF)	sudo apt install mupdf-tools	Quick clean + linearize
poppler-utils	sudo apt install poppler-utils	pdfinfo, pdfimages, pdftotext utilities

Inspection (Identify Bloat)

# Page count, size, fonts, metadata
pdfinfo input.pdf

# Object statistics — spot huge /FlateDecode streams or duplicate fonts
pdf-parser.py -a input.pdf

# Export full object graph as JSON; find largest streams
qpdf --json --json-stream-data=file input.pdf > /tmp/analysis.json
jq '[.qpdf[1] | to_entries[] | select(.value.stream) | {obj: .key, length: .value.stream.length}]
  | sort_by(-.length) | .[:20]' /tmp/analysis.json

Lossless Size Reduction

Automated (Zero Manual Editing)

# pdfsizeopt — best for duplicate fonts/streams/EML-style bloat
pdfsizeopt --use-pngout=no input.pdf output.pdf

# qpdf — recompress streams + generate object streams
qpdf --compress-streams=y --object-streams=generate --recompress-flate --linearize \
  input.pdf qpdf-opt.pdf

Manual Object Pruning via QDF

# Convert to human-readable QDF format
qpdf --qdf input.pdf editable.qdf

# Edit editable.qdf: locate huge object IDs from inspection step,
# delete entire "obj … endobj" blocks for unused /XObject or metadata.
# Then repack:
qpdf editable.qdf optimized.pdf

Lossy Reduction (Ghostscript)

gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/ebook \
  -dNOPAUSE -dQUIET -dBATCH -sOutputFile=gs-opt.pdf input.pdf

Preset options: /screen (72 dpi), /ebook (150 dpi), /printer (300 dpi), /prepress (300 dpi, color-preserving).

Post-Execution QA Gate

Always verify after any reduction:

ls -lh input.pdf optimized.pdf
pdfinfo optimized.pdf
diff <(pdfinfo input.pdf | grep -E 'Pages|Page size') \
     <(pdfinfo optimized.pdf | grep -E 'Pages|Page size')

Confirm: file size decreased, page count unchanged, page dimensions preserved.

What to Avoid

• Running Ghostscript first — it rewrites the entire document and cannot do object-level edits
• Using pdfcpu or exiftool alone — insufficient object-level control
• Skipping the inspection step — always identify bloat sources before attempting reduction

Related Skills

• robust-commands: You MUST load this skill when executing commands requiring resilient error recovery or fallbacks.