When to Use This Skill
- User mentions a
.pdf file and wants to read, extract, or inspect its content
- Text extraction: extract text from all or specific pages, with layout preservation
- Table extraction: extract tables as markdown, JSON, or CSV
- Metadata inspection: page count, title, author, creator, file size, encryption status
- PDF to images: render pages as PNG for visual inspection (scanned/image PDFs, charts, diagrams)
- Merge: combine multiple PDFs into one
- Split: extract page ranges into separate files
- Rotate: rotate specific pages
- Extract images: extract embedded images from a PDF
- Decrypt: remove password protection (when password is known)
Scanned / image PDFs: If text extraction returns empty or garbled results, the PDF is likely a scanned document. Use the to-images subcommand to convert pages to PNG — the AI agent can then read the content visually. This is more reliable and lightweight than OCR.
Prerequisites
pypdf — PDF manipulation (merge, split, rotate, metadata, decrypt, extract images)pdfplumber — text and table extractionpypdfium2 (optional) — PDF-to-image conversion (to-images subcommand)
Pre-flight check:
python3 -c "import pypdf; print('pypdf', pypdf.__version__)"
python3 -c "import pdfplumber; print('pdfplumber', pdfplumber.__version__)"
# Optional: check image conversion support
python3 -c "import pypdfium2; print('pypdfium2', pypdfium2.__version__)"
Install if missing:
pip install pypdf pdfplumber
pip install pypdfium2 # optional, for to-images
Workflow
- Determine what the user wants (read text, extract tables, inspect metadata, convert to images, merge, split, etc.)
- Run the appropriate script subcommand
- Read the output (text, markdown table, JSON, or confirmation) and present it to the user
- For multi-step tasks, chain subcommands in sequence
All commands use:
python3 scripts/pdf_ops.py <subcommand> [options] <file>
The script path is relative to this skill directory.
Command Reference
Inspect PDF metadata
python3 scripts/pdf_ops.py info document.pdf
Shows page count, title, author, subject, creator, producer, creation date, file size, and encryption status.
Extract text
# Extract text from all pages
python3 scripts/pdf_ops.py text document.pdf
# Extract text from specific pages (1-based)
python3 scripts/pdf_ops.py text document.pdf --pages 1-5
# Extract text from a single page
python3 scripts/pdf_ops.py text document.pdf --pages 3
# Combine specific pages and ranges
python3 scripts/pdf_ops.py text document.pdf --pages 1,3,5-8
# Extract with layout preservation (keeps spatial arrangement)
python3 scripts/pdf_ops.py text document.pdf --layout
Extract tables
# Extract all tables as markdown (default)
python3 scripts/pdf_ops.py tables document.pdf
# Extract tables from specific pages
python3 scripts/pdf_ops.py tables document.pdf --pages 2-4
# Extract as JSON
python3 scripts/pdf_ops.py tables document.pdf --format json
# Extract as CSV (one file per table)
python3 scripts/pdf_ops.py tables document.pdf --format csv --output-dir ./tables/
Convert PDF to images
Renders each page as a PNG image. Useful for scanned PDFs, charts, diagrams, or any visual content.
# Convert all pages (output to same directory as PDF)
python3 scripts/pdf_ops.py to-images document.pdf
# Convert specific pages
python3 scripts/pdf_ops.py to-images document.pdf --pages 1-3
# Output to a specific directory
python3 scripts/pdf_ops.py to-images document.pdf --output-dir ./pages/
# Control resolution (default: 2.0x scale)
python3 scripts/pdf_ops.py to-images document.pdf --scale 3.0
Output files are named <stem>_page_1.png, <stem>_page_2.png, etc.
Merge PDFs
# Merge multiple PDFs into one
python3 scripts/pdf_ops.py merge file1.pdf file2.pdf file3.pdf -o merged.pdf
# Merge all PDFs in a directory (alphabetical order)
python3 scripts/pdf_ops.py merge *.pdf -o combined.pdf
Split PDF
# Extract specific pages into a new PDF
python3 scripts/pdf_ops.py split document.pdf --pages 1-5 -o first_five.pdf
# Extract a single page
python3 scripts/pdf_ops.py split document.pdf --pages 3 -o page3.pdf
# Split into individual pages (one file per page)
python3 scripts/pdf_ops.py split document.pdf --each --output-dir ./pages/
Rotate pages
# Rotate all pages 90° clockwise
python3 scripts/pdf_ops.py rotate document.pdf 90 -o rotated.pdf
# Rotate specific pages
python3 scripts/pdf_ops.py rotate document.pdf 90 --pages 1,3 -o rotated.pdf
# Rotate counter-clockwise
python3 scripts/pdf_ops.py rotate document.pdf 270 -o rotated.pdf
Valid angles: 90, 180, 270.
Extract embedded images
# Extract all images to a directory
python3 scripts/pdf_ops.py extract-images document.pdf --output-dir ./images/
# Extract from specific pages
python3 scripts/pdf_ops.py extract-images document.pdf --pages 1-3 --output-dir ./images/
Decrypt a password-protected PDF
python3 scripts/pdf_ops.py decrypt encrypted.pdf --password secret -o decrypted.pdf
Composing Multi-Step Workflows
The commands above are building blocks. Combine them to accomplish complex user requests. Examples:
"Read this scanned PDF":
text to attempt text extraction — if empty, it's a scanned documentto-images to render pages as PNGs- Read the images visually
"Extract the tables from pages 3-5 and save as CSV":
tables --pages 3-5 --format csv --output-dir ./tables/ to extract and save
"Merge these three PDFs but only include pages 1-10 from the first one":
split to extract pages 1-10 from the first PDFmerge the split output with the other two PDFs
"What's in this PDF?":
info to see page count, title, etc.text --pages 1 to read the first page for a quick overview
Guidelines
- Read before manipulate: always
info or text --pages 1 first to understand the document
- Large PDFs: use
--pages to limit extraction to relevant pages
- Empty text extraction: if
text returns nothing, the PDF is likely scanned/image-based — use to-images and read visually
- Output files:
merge, split, rotate, and decrypt require -o for the output path; they never overwrite the input file
- Table extraction: not all PDFs have machine-readable tables; complex layouts may need visual inspection via
to-images
1---2name: pdf3description: Read, extract, and manipulate PDF files via a bundled Python script. Supports text extraction, table extraction (to markdown/JSON/CSV), metadata/info, PDF-to-image conversion, merge, split, rotate, extract embedded images, and password decrypt. Trigger whenever the user asks to read, inspect, extract, convert, merge, split, or manipulate a PDF file, or says phrases like "read pdf", "extract text from pdf", "pdf to text", "pdf tables", "pdf to image", "merge pdfs", "split pdf", "pdf info", "读 pdf", "看 pdf", "看看这个 pdf", "pdf 说了什么", "打开 pdf", "读一下 pdf", "提取 pdf 文字", "pdf 转图片", "合并 pdf", "拆分 pdf", "pdf 表格", "pdf 内容". Also trigger when the user mentions a .pdf file path and wants to inspect, read, or process it.4license: Apache-2.05---67# When to Use This Skill89- User mentions a `.pdf` file and wants to read, extract, or inspect its content10- Text extraction: extract text from all or specific pages, with layout preservation11- Table extraction: extract tables as markdown, JSON, or CSV12- Metadata inspection: page count, title, author, creator, file size, encryption status13- PDF to images: render pages as PNG for visual inspection (scanned/image PDFs, charts, diagrams)14- Merge: combine multiple PDFs into one15- Split: extract page ranges into separate files16- Rotate: rotate specific pages17- Extract images: extract embedded images from a PDF18- Decrypt: remove password protection (when password is known)1920> **Scanned / image PDFs**: If text extraction returns empty or garbled results, the PDF is likely a scanned document. Use the `to-images` subcommand to convert pages to PNG — the AI agent can then read the content visually. This is more reliable and lightweight than OCR.2122# Prerequisites2324- `pypdf` — PDF manipulation (merge, split, rotate, metadata, decrypt, extract images)25- `pdfplumber` — text and table extraction26- `pypdfium2` (optional) — PDF-to-image conversion (`to-images` subcommand)2728Pre-flight check:2930```bash31python3 -c "import pypdf; print('pypdf', pypdf.__version__)"32python3 -c "import pdfplumber; print('pdfplumber', pdfplumber.__version__)"33# Optional: check image conversion support34python3 -c "import pypdfium2; print('pypdfium2', pypdfium2.__version__)"35```3637Install if missing:3839```bash40pip install pypdf pdfplumber41pip install pypdfium2 # optional, for to-images42```4344# Workflow45461. Determine what the user wants (read text, extract tables, inspect metadata, convert to images, merge, split, etc.)472. Run the appropriate script subcommand483. Read the output (text, markdown table, JSON, or confirmation) and present it to the user494. For multi-step tasks, chain subcommands in sequence5051All commands use:5253```bash54python3 scripts/pdf_ops.py <subcommand> [options] <file>55```5657The script path is relative to this skill directory.5859# Command Reference6061## Inspect PDF metadata6263```bash64python3 scripts/pdf_ops.py info document.pdf65```6667Shows page count, title, author, subject, creator, producer, creation date, file size, and encryption status.6869## Extract text7071```bash72# Extract text from all pages73python3 scripts/pdf_ops.py text document.pdf7475# Extract text from specific pages (1-based)76python3 scripts/pdf_ops.py text document.pdf --pages 1-57778# Extract text from a single page79python3 scripts/pdf_ops.py text document.pdf --pages 38081# Combine specific pages and ranges82python3 scripts/pdf_ops.py text document.pdf --pages 1,3,5-88384# Extract with layout preservation (keeps spatial arrangement)85python3 scripts/pdf_ops.py text document.pdf --layout86```8788## Extract tables8990```bash91# Extract all tables as markdown (default)92python3 scripts/pdf_ops.py tables document.pdf9394# Extract tables from specific pages95python3 scripts/pdf_ops.py tables document.pdf --pages 2-49697# Extract as JSON98python3 scripts/pdf_ops.py tables document.pdf --format json99100# Extract as CSV (one file per table)101python3 scripts/pdf_ops.py tables document.pdf --format csv --output-dir ./tables/102```103104## Convert PDF to images105106Renders each page as a PNG image. Useful for scanned PDFs, charts, diagrams, or any visual content.107108```bash109# Convert all pages (output to same directory as PDF)110python3 scripts/pdf_ops.py to-images document.pdf111112# Convert specific pages113python3 scripts/pdf_ops.py to-images document.pdf --pages 1-3114115# Output to a specific directory116python3 scripts/pdf_ops.py to-images document.pdf --output-dir ./pages/117118# Control resolution (default: 2.0x scale)119python3 scripts/pdf_ops.py to-images document.pdf --scale 3.0120```121122Output files are named `<stem>_page_1.png`, `<stem>_page_2.png`, etc.123124## Merge PDFs125126```bash127# Merge multiple PDFs into one128python3 scripts/pdf_ops.py merge file1.pdf file2.pdf file3.pdf -o merged.pdf129130# Merge all PDFs in a directory (alphabetical order)131python3 scripts/pdf_ops.py merge *.pdf -o combined.pdf132```133134## Split PDF135136```bash137# Extract specific pages into a new PDF138python3 scripts/pdf_ops.py split document.pdf --pages 1-5 -o first_five.pdf139140# Extract a single page141python3 scripts/pdf_ops.py split document.pdf --pages 3 -o page3.pdf142143# Split into individual pages (one file per page)144python3 scripts/pdf_ops.py split document.pdf --each --output-dir ./pages/145```146147## Rotate pages148149```bash150# Rotate all pages 90° clockwise151python3 scripts/pdf_ops.py rotate document.pdf 90 -o rotated.pdf152153# Rotate specific pages154python3 scripts/pdf_ops.py rotate document.pdf 90 --pages 1,3 -o rotated.pdf155156# Rotate counter-clockwise157python3 scripts/pdf_ops.py rotate document.pdf 270 -o rotated.pdf158```159160Valid angles: 90, 180, 270.161162## Extract embedded images163164```bash165# Extract all images to a directory166python3 scripts/pdf_ops.py extract-images document.pdf --output-dir ./images/167168# Extract from specific pages169python3 scripts/pdf_ops.py extract-images document.pdf --pages 1-3 --output-dir ./images/170```171172## Decrypt a password-protected PDF173174```bash175python3 scripts/pdf_ops.py decrypt encrypted.pdf --password secret -o decrypted.pdf176```177178# Composing Multi-Step Workflows179180The commands above are building blocks. Combine them to accomplish complex user requests. Examples:181182**"Read this scanned PDF":**1831. `text` to attempt text extraction — if empty, it's a scanned document1842. `to-images` to render pages as PNGs1853. Read the images visually186187**"Extract the tables from pages 3-5 and save as CSV":**1881. `tables --pages 3-5 --format csv --output-dir ./tables/` to extract and save189190**"Merge these three PDFs but only include pages 1-10 from the first one":**1911. `split` to extract pages 1-10 from the first PDF1922. `merge` the split output with the other two PDFs193194**"What's in this PDF?":**1951. `info` to see page count, title, etc.1962. `text --pages 1` to read the first page for a quick overview197198# Guidelines199200- **Read before manipulate**: always `info` or `text --pages 1` first to understand the document201- **Large PDFs**: use `--pages` to limit extraction to relevant pages202- **Empty text extraction**: if `text` returns nothing, the PDF is likely scanned/image-based — use `to-images` and read visually203- **Output files**: `merge`, `split`, `rotate`, and `decrypt` require `-o` for the output path; they never overwrite the input file204- **Table extraction**: not all PDFs have machine-readable tables; complex layouts may need visual inspection via `to-images`
jie-meng