Pdf handling

Skill iceflower/agent-skills/pdf-handling

Agent Skills 오픈 표준 기반 AI 코딩 에이전트용 스킬 컬렉션 (Java, Kotlin, Spring, NestJS, K8s, Terraform, GraphQL, gRPC, OpenTelemetry, a11y, i18n 등 60개)

Install

npx -y skills add iceflower/agent-skills --skill pdf-handling

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

PDF file reading and processing rules. Use when analyzing PDF files or extracting content from them.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

4.1 KB, 929 tokens by cl100k_base, as published. Nobody here has run it

PDF File Handling Rules

Conversion Procedure

When reading PDF files, always follow this procedure:
1. Convert the required pages to PNG images using pdftoppm
2. Analyze the converted images to extract text
Never include a PDF file directly in an API request body

Prerequisite

poppler must be installed
- macOS: brew install poppler
- openSUSE Tumbleweed: sudo zypper install poppler-tools
- Ubuntu (LTS): sudo apt install poppler-utils
- Windows: choco install poppler or scoop install poppler

Page Range Strategy

Read table of contents pages first to understand structure
Convert only the pages needed for the current task, not the entire document
For large PDFs (100+ pages), work in batches of 10-20 pages

Temporary File Management

Use /tmp/ for converted PNG images
Use descriptive prefixes for output files (e.g., pdftoppm -png -f 1 -l 5 input.pdf /tmp/project_toc)
Clean up temporary PNG files after extraction is complete using rm /tmp/<prefix>*.png

Large PDF Handling

If the Read tool fails due to file size, always fall back to pdftoppm
Estimate the PDF page offset by comparing displayed page numbers with actual PDF page numbers
When searching for specific content, use the table of contents to calculate target page numbers rather than scanning sequentially

Command Reference

pdftoppm

# Convert specific page range to PNG
pdftoppm -png -f <first> -l <last> input.pdf /tmp/output_prefix

# Example: convert pages 1-5
pdftoppm -png -f 1 -l 5 input.pdf /tmp/project_toc

# Higher resolution (default 150 DPI, use 300 for small text)
pdftoppm -png -r 300 -f 1 -l 1 input.pdf /tmp/high_res

pdfinfo

# Check page count, file size, and metadata
pdfinfo input.pdf

pdftotext

# Extract text from specific pages (preserve layout)
pdftotext -f 1 -l 5 -layout input.pdf /tmp/output.txt

# Extract all text
pdftotext input.pdf /tmp/output.txt

Workflow

Standard PDF Analysis Procedure

1. Run pdfinfo to check document metadata (page count, size)
2. Convert table of contents pages with pdftoppm to understand structure
3. Selectively convert only the pages needed for the task
4. Analyze images or extract text with pdftotext
5. Clean up temporary files in /tmp/

Page Number Offset Handling

The actual PDF page number and the printed page number in the document may differ.

Situation	Example	Resolution
Cover/preface pages present	Document "page 1" is PDF page 3	Apply offset +2
Roman numeral pages	i, ii, iii, ...	Cross-reference with table of contents
Appendix with separate numbers	A-1, A-2, ...	Calculate from table of contents

Library and Tool References

See references/pdf-libraries.md for detailed comparison of PDF libraries (Apache PDFBox, iText, pdf.js, pypdf, pdfplumber, and others) including licensing, capabilities, and selection guide. See references/pdf-text-extraction.md for text/table extraction techniques (Camelot, Tabula, pdfplumber) and OCR guide with Tesseract.

Anti-Patterns

Converting the entire PDF at once (memory/disk exhaustion on large files)
Not cleaning up temporary PNG files after extraction
Converting pages without verifying the page number offset
Using image conversion when direct text extraction (pdftotext) is sufficient

Related Skills

error-handling: Error handling patterns for PDF parsing failures
logging: Logging PDF processing workflows
testing: Testing strategies for PDF processing logic

What ships with it: 4 files

25.3 KB alongside SKILL.md, 1 of them executable

references/

pdf-libraries.md5.9 KB
pdf-text-extraction.md8.5 KB

scripts/

pdf_extract.pyruns10.2 KB

README.md713 B

Gives 0 of the 12 instructions most pdf office docs skills give in 929 tokens

Counted across 636 of the 690 authors here whose files we hold, read 2026-08-07

extract text using pdfplumberin 89 of 636, across 23 files
create PDFs using reportlabin 83 of 636, across 16 files
read forms.md to fill out pdf formsin 80 of 636, across 13 files
OCR scanned PDFs using pytesseractin 77 of 636, across 10 files
merge or split PDFs using qpdfin 70 of 636, across 3 files
use excel formulas instead of hardcoded calculated valuesin 68 of 636, across 13 files
unpack edit xml and repack existing documentsin 63 of 636, across 8 files
document sources for hardcoded valuesin 61 of 636, across 9 files
write minimal python code without unnecessary commentsin 59 of 636, across 7 files
run the recalculation script after adding or modifying formulasin 59 of 636, across 7 files
fix all identified formula errors and recalculatein 58 of 636, across 6 files
format years as text stringsin 57 of 636, across 5 files

Said here and by no other author read

install poppler before processing
read table of contents pages first
convert only required pages
store temporary png files in tmp
check pdf metadata using pdfinfo
fall back to pdftoppm if read tool fails

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.