| 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:
- Matching executable under this skill's
scripts/ directory.
- Auto-download the matching uncompressed executable from the latest GitHub Release into this skill's
scripts/ directory.
target/release/pdf-shrink in the current repository, only when the current working directory is a pdf-shrink source checkout.pdf-shrink available on PATH.- 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
- Resolve the official
pdf-shrink executable using the mandatory resolver order above.
- If no official executable can be resolved, stop with an error instead of trying unrelated PDF tools.
- Choose an explicit output path so the original file is preserved.
- Unless the user explicitly asks for another compression level, use the default
best-quality profile. Prefer omitting --profile so the CLI default is used.
- 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.
- If the user wants to compare sizes/quality or is unsure which profile to choose, run
--all-profiles to create comparable candidates.
- Review the CLI report for skipped image filters/masks; skipped images explain limited compression.
- 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
