PDF

PDF read, create, edit, review + vision-based extraction. This skill handles the full lifecycle of PDF documents — from generating new files with reportlab to extracting text with pdfplumber, rendering pages to images with Poppler, and performing visual quality verification after every edit.

Reference AI & Media

Reference skill: pdf is not active by default. Install it with jaw skill install pdf or say "PDF 스킬 설치해줌" in chat. Once active, it is injected into the system prompt and the agent follows its workflow automatically whenever PDF tasks are detected.

Quick Reference

Skill name	`pdf`
Category	AI & Media
Default active	No — requires `jaw skill install pdf`
SKILL.md path	`~/.cli-jaw/skills/pdf/SKILL.md` (active) or `~/.cli-jaw/skills_ref/pdf/SKILL.md` (ref)
Python packages	`reportlab`, `pdfplumber`, `pypdf`
System tools	`pdftoppm` (from Poppler)
Temp directory	`tmp/pdfs/`
Output directory	`output/pdf/`
Related skills	`pdf-vision`, `docx`, `pptx`, `xlsx`

Workflow

When the pdf skill is active, the agent follows a strict four-step workflow for every PDF task:

Step	Action	Tools Used
1. Render	Render PDF pages to PNG images for visual review	`pdftoppm` (Poppler). Falls back to asking the user if Poppler is unavailable.
2. Generate	Create new PDFs or edit existing ones	`reportlab` for creation; `pypdf` for merging/splitting; `nano-pdf` for natural-language page edits
3. Extract	Pull text and data from PDF files	`pdfplumber` or `pypdf` for text extraction (note: layout fidelity is unreliable)
4. Verify	Re-render and visually confirm quality after each meaningful update	`pdftoppm` + visual inspection of alignment, spacing, and legibility

Verify-after-edit loop: The skill mandates re-rendering after every meaningful change. The agent will not deliver a PDF without first confirming zero visual defects in the latest PNG render. This is the most important rule in the skill.

Dependencies

The skill auto-detects missing dependencies and will attempt to install them. If installation is blocked (permissions, network), the agent tells you exactly what is missing and how to install it manually.

reportlab uv pip install reportlab

PDF generation: layout, text, tables, images, and vector graphics

pdfplumber uv pip install pdfplumber

Text extraction with positional data, table detection, and page geometry

pypdf uv pip install pypdf

PDF manipulation: merge, split, rotate, encrypt, and metadata editing

Poppler (pdftoppm) brew install poppler

Render PDF pages to high-quality PNG images for visual verification

The skill prefers uv for Python dependency management. If uv is unavailable, it falls back to python3 -m pip install.

Full install commands

# Python packages (preferred: uv)
uv pip install reportlab pdfplumber pypdf

# Python packages (fallback: pip)
python3 -m pip install reportlab pdfplumber pypdf

# System tools: macOS (Homebrew)
brew install poppler

# System tools: Ubuntu/Debian
sudo apt-get install -y poppler-utils

Rendering Command

The core rendering command converts PDF pages to PNG images:

pdftoppm -png $INPUT_PDF $OUTPUT_PREFIX

This produces files like $OUTPUT_PREFIX-1.png, $OUTPUT_PREFIX-2.png, etc. — one PNG per page. The agent reads these images to verify layout quality before delivering the final PDF.

File Conventions

Directory	Purpose	Lifecycle
`tmp/pdfs/`	Intermediate renders, draft PDFs, PNG previews	Deleted after task completion
`output/pdf/`	Final deliverable PDF files	Persisted; stable descriptive filenames

Filename stability: The skill keeps filenames stable and descriptive across edits. Avoid random suffixes or timestamps in final output names. Use clear names like quarterly-report-2026-Q1.pdf or invoice-0042.pdf.

Quality Rules

The skill enforces strict visual and typographic standards. Every PDF produced must pass these checks:

Rule	Detail
Typography	Consistent fonts, sizes, and weights across the document. No mixed typefaces unless intentional.
Spacing & margins	Uniform margins, line spacing, and section gaps. No cramped or overflowing content.
Section hierarchy	Clear visual distinction between headings, subheadings, and body text.
No rendering defects	Zero clipped text, overlapping elements, broken tables, black squares, or unreadable glyphs.
Charts & tables	Sharp rendering, correct alignment, clearly labeled axes and headers.
Images	No blurring, correct aspect ratio, properly positioned within the layout.
ASCII hyphens only	Use standard ASCII hyphens (`-`). Unicode dashes (e.g., U+2011 non-breaking hyphen) cause rendering issues in some PDF viewers.
Citations & references	Human-readable text only. No tool tokens, placeholder markers, or raw IDs.

Final Delivery Checklist

Before marking a PDF task as complete, the agent runs through this checklist:

Verify the latest PNG render shows zero visual defects.
Confirm headers and footers appear correctly on every page.
Verify page numbering is sequential and correctly positioned.
Check section transitions — no orphaned headings or widowed paragraphs.
Clean up intermediate files in tmp/pdfs/ after user approval.

DOCX-to-PDF Conversion

The skill also covers converting Word documents to PDF using LibreOffice:

# Convert DOCX to PDF via soffice (LibreOffice headless)
soffice --headless --convert-to pdf input.docx --outdir output/pdf/

This is useful when the source material is a Word document and the final deliverable must be PDF. The agent will still run the full verify-after-render loop on the converted output.

Capabilities Summary

Capability	Tool	Notes
Create new PDFs	`reportlab`	Full control over layout, fonts, tables, images, and vector graphics
Read / extract text	`pdfplumber`, `pypdf`	Text extraction; layout fidelity is approximate, not pixel-perfect
Edit existing PDFs	`nano-pdf`	Natural-language page edits on existing PDF content
Merge / split	`pypdf`	Combine multiple PDFs or extract page ranges
Render to image	`pdftoppm`	High-quality PNG renders for visual QA
DOCX conversion	`soffice`	LibreOffice headless Word-to-PDF conversion
Visual QA	Agent vision	Agent reads rendered PNGs to verify quality

"~해줌" Usage Examples

These are real-world examples of how to invoke PDF tasks in natural language. Korean and English both work.

"이 보고서 PDF로 만들어줌 — 표지, 목차, 본문 3장"

Creates a new PDF document with a cover page, table of contents, and 3 pages of body content using reportlab. The agent will render each page to PNG and verify layout before delivery.

"이 PDF에서 텍스트 추출해줌 — 표 데이터도 포함해서"

Extracts all text and table data from the given PDF using pdfplumber. Returns structured text with table rows preserved. Warns if layout fidelity is unreliable for the specific document.

"이 두 PDF 합쳐줌 — report-part1.pdf랜령 report-part2.pdf"

Merges two PDF files into a single document using pypdf. Preserves page numbering and bookmarks. Output goes to output/pdf/.

"이 계약서 PDF 2페이지 날짜 수정해줌"

Edits page 2 of an existing contract PDF using nano-pdf (natural-language editing). After the edit, the agent re-renders the page and visually verifies that the date change is correct and nothing else shifted.

"Word 파일 PDF로 변환해줌 — proposal.docx"

Converts a DOCX file to PDF using LibreOffice headless mode (soffice --headless --convert-to pdf). The agent then renders the output to PNG and checks for any formatting issues introduced during conversion.

Comparison with pdf-vision

CLI-JAW ships two PDF-related skills. They are complementary, not redundant:

	`pdf`	`pdf-vision`
Focus	Create, edit, extract, and merge PDFs	Vision-based analysis of existing PDFs
Best for	Generating reports, editing documents, extracting text	OCR on scanned docs, layout understanding, table extraction from images
Tools	reportlab, pdfplumber, pypdf, pdftoppm	Vision model, OCR pipeline
When to use both	When you need to extract data from a scanned PDF (`pdf-vision`) and then generate a new clean PDF from that data (`pdf`).

Tip: Install both with jaw skill install pdf pdf-vision or say "PDF 스킬이량 pdf-vision 둘 다 설치해줌". They work together seamlessly when both are active.

Troubleshooting

Poppler not found

If the agent reports that pdftoppm is not available, install Poppler:

# macOS
brew install poppler

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

# Verify
pdftoppm -v

Unicode dash rendering issues

If you see garbled or missing characters in hyphens and dashes, the source data may contain Unicode dashes (U+2011, U+2013, U+2014). The skill enforces ASCII hyphens (-) to avoid viewer compatibility issues. The agent will auto-replace these during generation.

Layout fidelity warnings

pdfplumber and pypdf extract text based on character positions, not visual layout. Complex multi-column layouts, overlapping text boxes, and rotated text may not extract correctly. For those cases, consider using pdf-vision instead, which uses visual analysis rather than text-stream parsing.

LibreOffice not installed

DOCX-to-PDF conversion requires LibreOffice. If soffice is not found:

# macOS
brew install --cask libreoffice

# Ubuntu/Debian
sudo apt-get install -y libreoffice

Installation

# CLI
jaw skill install pdf

# In-chat (Korean)
"PDF 스킬 설치해줌"

# In-chat (English)
"Install the PDF skill"

# Verify installation
jaw skill info pdf

# Expected output of jaw skill info pdf:
#   Name:     pdf
#   Status:   active
#   Category: AI & Media
#   Path:     ~/.cli-jaw/skills/pdf/SKILL.md
#   Description: PDF creation, reading, editing, merging, and text extraction

AI Media Skills PDF Vision