pdf-compression

Compress scanned and image-heavy PDFs by downscaling and re-encoding embedded images.

1|Updated May 8, 2026
One-click install
npx skills add https://github.com/franklinbaldo/skills --skill pdf-compression-franklinbaldo
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: pdf-compression
Source: https://github.com/franklinbaldo/skills/tree/main/pdf-compression
Command: npx skills add https://github.com/franklinbaldo/skills --skill pdf-compression-franklinbaldo

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pymupdf, pillow, numpy, opencv-python-headless, cyclopts, and includes scripts (resource) components.

What problem does it solve? Large scanned or image-heavy PDFs (such as digitized court records) are too big to email, upload, or archive efficiently. This Skill reduces their size by extracting embedded images, downscaling them, and re-encoding them with CCITT Group 4, JPEG, or JBIG2 compression. ## Core Features & Use Cases - Smart compression modes: Automatically detects scanned versus native digital pages, binarizing scanned pages to black-and-white CCITT G4 while preserving color on digital pages to protect charts and logos. - Bookmark-based splitting and N-up layouts: Splits large PDFs by table-of-contents bookmarks, applies 2-up/4-up page layouts, compresses each part with rasterization fallbacks, and re-merges with rebuilt bookmarks. - Optional JBIG2 backend: Uses the jbig2enc binary for lossless encoding when it verifies pixel-exact and beats CCITT G4's real saved size. - Use Case: A 500 MB scanned court case file needs to fit an e-filing portal limit. Run the compression script in auto mode to binarize scanned pages and shrink the file dramatically while keeping text readable. ## Quick Start Ask the agent to compress a large scanned PDF to black-and-white at a readable resolution, for example: "Compress this scanned PDF to the smallest readable size using bw mode."

Frequently Asked Questions about pdf-compression

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I compress a large scanned PDF file?▼

Run the compress.py script with uv, passing --input and --output paths and a mode such as bw for black-and-white scanned text. The script downscales images and re-encodes them with CCITT Group 4 or JPEG, typically achieving large size reductions.

What is the difference between bw, gray, color, and auto PDF compression modes?▼

The bw mode binarizes images to 1-bit CCITT G4 for maximum compression of scanned text, gray uses 8-bit JPEG, and color preserves colors with JPEG. Auto mode detects scanned versus digital pages and applies bw to scans while keeping color on native digital pages.

How do I split a PDF by bookmarks and apply a 2-up layout?▼

Use the process_pdf.py script with --input, --output-dir, and --nup 2. It splits the PDF by level-1 bookmarks, applies the N-up layout, compresses each part with rasterization fallback for oversized sections, and re-merges everything with rebuilt bookmarks.

Does the JBIG2 compression option work on Windows or Fedora?▼

JBIG2 requires the jbig2enc binary, which is packaged for Debian/Ubuntu (apt-get install jbig2) and macOS (brew install jbig2enc) but not in Fedora's or Arch's official repos. On Windows, use WSL or a similar Linux userland approach; without the binary, the script falls back to CCITT G4.

Why did bw mode make my PDF charts unreadable?▼

The bw mode binarizes images into high-contrast black and white, which destroys color information in photos, graphs, and diagrams. Use color or gray mode for documents where color detail matters, or auto mode to binarize only detected scanned pages.

Why does the script fail when run with plain python instead of uv?▼

The scripts declare dependencies inline via PEP 723 headers, which only uv resolves automatically. Running with plain python fails when pymupdf, pillow, or opencv-python-headless are missing from the global environment, so always invoke scripts with uv run.