pdf-shrink

name	pdf-shrink
description	Compress PDF files with the local Rust `pdf-shrink` CLI by recompressing/downsampling embedded images and applying PDF stream compression. Use when a user wants to reduce PDF file size, tune JPEG quality, downscale embedded images to screen DPI, compare compression profiles, or batch-compress PDFs while preserving text and vector content.

pdf-shrink

Use this skill to compress PDF files with the pdf-shrink command-line tool in this repository.

What this tool does

pdf-shrink reduces PDF size by:

• Recompressing embedded JPEG images that use the PDF DCTDecode filter.
• Converting safe 8-bit FlateDecode RGB/grayscale image XObjects to JPEG.
• Downscaling images by profile, explicit scale, or target screen DPI.
• Applying lossless compression to other PDF streams.

It preserves PDF text and vector content. It skips images with masks/transparency and unsupported filters such as LZWDecode, CCITTFaxDecode, or JPXDecode.

Tool resolution is mandatory

This skill must run the official pdf-shrink executable only. Do not use any other PDF compressor or OS PDF API as a fallback.

Forbidden fallbacks include, but are not limited to: gs, Ghostscript, qpdf, mutool, pdfimages, ImageMagick magick/convert, macOS Preview, Quartz filters, PDFKit helper programs, Automator actions, AppleScript, browser print-to-PDF, online services, package-manager installs, or newly generated helper source code.

Before compressing PDFs, resolve the executable in this exact order and stop as soon as one step succeeds:

1. Matching executable under this skill's scripts/ directory.
2. Auto-download the matching uncompressed executable from the latest GitHub Release into this skill's scripts/ directory.
3. target/release/pdf-shrink in the current repository, only when the current working directory is a pdf-shrink source checkout.
4. pdf-shrink available on PATH.
5. Build from source with cargo build --release, only when the current working directory is a pdf-shrink source checkout.

If all five steps fail, stop and report that the official pdf-shrink executable could not be resolved. Do not search for or run alternative PDF tools.

Skill directory and scripts directory

SKILL_DIR means the directory that contains this SKILL.md file. It is not necessarily the repository's skills/pdf-shrink path after the skill is installed.

Always store downloaded executables in:

<SKILL_DIR>/scripts/<asset-name>

For example, if the skill is installed at /Users/will/.agents/skills/pdf-shrink, the macOS Apple Silicon executable must be downloaded to:

/Users/will/.agents/skills/pdf-shrink/scripts/pdf-shrink-aarch64-apple-darwin

Create <SKILL_DIR>/scripts/ if it does not exist.

Platform asset mapping

Detect the current platform once, map it to exactly one release asset, then use only that asset name.

Platform	CPU	Release asset
macOS	Apple Silicon / arm64	pdf-shrink-aarch64-apple-darwin
macOS	Intel / x86_64	pdf-shrink-x86_64-apple-darwin
Linux	x86_64	pdf-shrink-x86_64-unknown-linux-gnu
Linux	aarch64 / arm64	pdf-shrink-aarch64-unknown-linux-gnu
Windows	AMD64 / x86_64	pdf-shrink-x86_64-pc-windows-msvc.exe
Windows	ARM64 / aarch64	pdf-shrink-aarch64-pc-windows-msvc.exe

Do not try similar names. Do not scan release archives. Do not infer a different target triple.

Download rules

Only download the exact uncompressed executable asset listed above. Do not download .zip, .tar.xz, .tar.gz, .msi, .pkg, .deb, .rpm, installer scripts, Homebrew formulae, Scoop manifests, or any archive/package that requires extraction or installation.

Download from:

https://github.com/doggy8088/pdf-shrink/releases/latest/download/<asset-name>

Save the response body directly to <SKILL_DIR>/scripts/<asset-name>. On Unix, run chmod +x <SKILL_DIR>/scripts/<asset-name> before executing it.

If <asset-name>.sha256 is available from the same release, download it to <SKILL_DIR>/scripts/<asset-name>.sha256 and verify the executable. If checksum download is unavailable, continue only if the executable download succeeded and the file is non-empty.

Treat the download as failed if the HTTP status is not successful, the saved file is empty, or the downloaded file is HTML/XML/JSON error text instead of a binary executable.

Exact resolver template

Follow this structure. Replace SKILL_DIR with the directory containing this SKILL.md.

set -euo pipefail

SKILL_DIR="/absolute/path/to/the/directory/containing/SKILL.md"
SCRIPTS_DIR="$SKILL_DIR/scripts"
mkdir -p "$SCRIPTS_DIR"

case "$(uname -s):$(uname -m)" in
  Darwin:arm64) ASSET="pdf-shrink-aarch64-apple-darwin" ;;
  Darwin:x86_64) ASSET="pdf-shrink-x86_64-apple-darwin" ;;
  Linux:x86_64) ASSET="pdf-shrink-x86_64-unknown-linux-gnu" ;;
  Linux:aarch64|Linux:arm64) ASSET="pdf-shrink-aarch64-unknown-linux-gnu" ;;
  *) echo "Unsupported platform for pdf-shrink auto-download" >&2; exit 1 ;;
esac

TOOL="$SCRIPTS_DIR/$ASSET"

if [ ! -x "$TOOL" ]; then
  URL="https://github.com/doggy8088/pdf-shrink/releases/latest/download/$ASSET"
  TMP="$TOOL.tmp"
  curl -fL "$URL" -o "$TMP"
  test -s "$TMP"
  chmod +x "$TMP"
  mv "$TMP" "$TOOL"
fi

After this resolver succeeds, run "$TOOL" for compression. Do not replace "$TOOL" with another PDF command, and do not run find to discover other executables.

Build the tool

From the repository root:

cargo build --release

The release binary is created at:

target/release/pdf-shrink

For quick local runs during development, cargo run -- is also acceptable. Building is allowed only when no suitable skill-local, repository-local, PATH, or downloadable official release binary is available and the current working directory is a pdf-shrink source checkout.

Basic usage

All compression examples assume the mandatory resolver has already set TOOL to the official pdf-shrink executable.

"$TOOL" \
  --input original.pdf \
  --output compressed.pdf

Development-only equivalent when working inside a pdf-shrink source checkout:

cargo run -- \
  --input original.pdf \
  --output compressed.pdf

Arguments

Argument	Required	Default	Purpose
--input, -i	Yes	None	Source PDF path.
--output, -o	No	Adds _compressed before the input extension	Destination PDF path.
--profile	No	best-quality	Compression preset: best-quality, quality, balanced, screen, or extreme.
--quality, -q	No	Profile value	JPEG quality from 0 to 100; lower values usually produce smaller files with more quality loss.
--scale, -s	No	Profile value	Extra image scale factor; 0.5 halves width and height, 1.0 preserves dimensions.
--target-dpi	No	Profile value	Downsample images based on their displayed page size for screen viewing.
--min-dimension	No	64	Minimum resized width/height to avoid destroying small icons.
--dry-run	No	false	Analyze compressibility and skip writing an output PDF.
--all-profiles	No	false	Create best-quality/quality/balanced/screen/extreme candidates and print a comparison table.
--output-dir	No	Input directory	Output directory for --all-profiles candidates.

Recommended workflow

1. Resolve the official pdf-shrink executable using the mandatory resolver order above.
2. If no official executable can be resolved, stop with an error instead of trying unrelated PDF tools.
3. Choose an explicit output path so the original file is preserved.
4. Unless the user explicitly asks for another compression level, use the default best-quality profile. Prefer omitting --profile so the CLI default is used.
5. Use --profile screen only when the user asks for stronger screen-viewing compression, and use --profile extreme only when they explicitly prioritize the smallest file over image quality.
6. If the user wants to compare sizes/quality or is unsure which profile to choose, run --all-profiles to create comparable candidates.
7. Review the CLI report for skipped image filters/masks; skipped images explain limited compression.
8. Compare file sizes and visually inspect important pages before replacing or sharing the compressed PDF.

Safety and validation

Always preserve the original PDF. This tool performs lossy JPEG recompression, so repeated compression can degrade image quality.

After compression, verify that:

• The command exited successfully.
• The output PDF exists and has non-zero size.
• The output is smaller than the input when size reduction was expected.
• Important pages still render acceptably.

Useful size check:

ls -lh original.pdf compressed.pdf

Examples

Create presentation_compressed.pdf automatically with the default best-quality profile:

"$TOOL" --input presentation.pdf

Create an explicit best-quality compressed copy:

"$TOOL" \
  --input report.pdf \
  --output report-best-quality.pdf \
  --profile best-quality

Create a more aggressive compressed copy:

"$TOOL" \
  --input report.pdf \
  --output report-small.pdf \
  --profile extreme

Create comparable compression candidates:

"$TOOL" \
  --input report.pdf \
  --all-profiles \
  --output-dir compressed-candidates

Batch-compress PDFs in the current directory while writing outputs to a separate folder:

mkdir -p compressed
for pdf in *.pdf; do
  "$TOOL" \
    --input "$pdf" \
    --output "compressed/${pdf%.pdf}-compressed.pdf"
done