pdf skill

safe

This skill helps you read, generate, and validate PDFs with reliable visuals and layout checks using Poppler, ReportLab, and pdfplumber.

npx playbooks add skill openai/skills --skill pdf

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

2.5 KB

---
name: "pdf"
description: "Use when tasks involve reading, creating, or reviewing PDF files where rendering and layout matter; prefer visual checks by rendering pages (Poppler) and use Python tools such as `reportlab`, `pdfplumber`, and `pypdf` for generation and extraction."
---


# PDF Skill

## When to use
- Read or review PDF content where layout and visuals matter.
- Create PDFs programmatically with reliable formatting.
- Validate final rendering before delivery.

## Workflow
1. Prefer visual review: render PDF pages to PNGs and inspect them.
   - Use `pdftoppm` if available.
   - If unavailable, install Poppler or ask the user to review the output locally.
2. Use `reportlab` to generate PDFs when creating new documents.
3. Use `pdfplumber` (or `pypdf`) for text extraction and quick checks; do not rely on it for layout fidelity.
4. After each meaningful update, re-render pages and verify alignment, spacing, and legibility.

## Temp and output conventions
- Use `tmp/pdfs/` for intermediate files; delete when done.
- Write final artifacts under `output/pdf/` when working in this repo.
- Keep filenames stable and descriptive.

## Dependencies (install if missing)
Prefer `uv` for dependency management.

Python packages:
```
uv pip install reportlab pdfplumber pypdf
```
If `uv` is unavailable:
```
python3 -m pip install reportlab pdfplumber pypdf
```
System tools (for rendering):
```
# macOS (Homebrew)
brew install poppler

# Ubuntu/Debian
sudo apt-get install -y poppler-utils
```

If installation isn't possible in this environment, tell the user which dependency is missing and how to install it locally.

## Environment
No required environment variables.

## Rendering command
```
pdftoppm -png $INPUT_PDF $OUTPUT_PREFIX
```

## Quality expectations
- Maintain polished visual design: consistent typography, spacing, margins, and section hierarchy.
- Avoid rendering issues: clipped text, overlapping elements, broken tables, black squares, or unreadable glyphs.
- Charts, tables, and images must be sharp, aligned, and clearly labeled.
- Use ASCII hyphens only. Avoid U+2011 (non-breaking hyphen) and other Unicode dashes.
- Citations and references must be human-readable; never leave tool tokens or placeholder strings.

## Final checks
- Do not deliver until the latest PNG inspection shows zero visual or formatting defects.
- Confirm headers/footers, page numbering, and section transitions look polished.
- Keep intermediate files organized or remove them after final approval.

Overview

This skill handles reading, creating, and reviewing PDF files where rendering and layout matter. It emphasizes visual checks by rendering pages and uses Python tools for generation and extraction. The goal is reliable, polished PDFs with verified visual fidelity before delivery.

How this skill works

Render PDF pages to PNGs (using Poppler's pdftoppm) and inspect them visually for layout, spacing, and legibility. Use reportlab to generate PDFs programmatically and pdfplumber or pypdf for text extraction and quick content checks, while avoiding reliance on extraction for layout validation. After each meaningful change, re-render pages and confirm there are no visual defects.

When to use it

Producing print-ready documents where typography, spacing, and alignment are critical.
Reviewing or proofreading PDFs to catch visual defects like clipping or overlapping elements.
Extracting text for metadata, search indexes, or lightweight validation while preserving original files.
Validating charts, tables, and images for sharpness and correct labeling before publication.
Automating PDF generation for reports, invoices, or formatted exports with consistent styling.

Best practices

Prefer visual review: always render pages to PNG and inspect final output before delivery.
Use reportlab for controlled PDF generation and keep style rules (fonts, margins, hierarchy) consistent.
Use pdfplumber or pypdf for extraction and quick checks, but not as proof of rendering fidelity.
Store intermediate files under tmp/pdfs/ and final artifacts under output/pdf/ with stable, descriptive filenames.
Re-render after each meaningful update and remove or archive intermediate files when finished.
Avoid non-standard hyphens and unreadable glyphs; ensure citations are human-readable and free of placeholders.

Example use cases

Generate monthly financial reports with precise headers, footers, and page numbering.
Review and fix a previously produced PDF that has clipped text or broken table layouts.
Create templated invoices using reportlab and confirm visual consistency across clients.
Extract and validate body text from scanned reports using pdfplumber, then re-render for layout checks.
Render PDF pages to PNG for a visual QA step in a CI pipeline before publishing.

FAQ

What rendering command should I use to create PNGs from a PDF?

Use pdftoppm -png $INPUT_PDF $OUTPUT_PREFIX to render pages to PNG files.

Which Python packages are recommended for generation and extraction?

Install reportlab for generation and pdfplumber or pypdf for extraction and quick checks.