pdf

Files (1)

• SKILL.md

SKILL.md (first lines)

# PDF Processing Guide

## Tool-First Workflow

Use the `Pdf` tool for ALL standard operations. Do NOT use Python/pypdf unless you need features the tool doesn't have.

### Available Pdf tool actions

| Task | Tool call |
|------|-----------|
| Inspect PDF metadata | `Pdf { action: "inspect", file_path: "doc.pdf" }` |
| Extract all text | `Pdf { action: "extract_text", file_path: "doc.pdf" }` |
| Extract text per page | `Pdf { action: "extract_pages_text", file_path: "doc.pdf" }` |
| Split pages | `Pdf { action: "split", file_path: "doc.pdf", pages: "1-3", output_path: "out.pdf" }` |
| Merge PDFs | `Pdf { action: "merge", file_paths: ["a.pdf", "b.pdf"], output_path: "merged.pdf" }` |
| Get form fields | `Pdf { action: "get_form_fields", file_path: "form.pdf" }` |
| Fill fillable form | `Pdf { action: "fill_form", file_path: "form.pdf", field_values: {"name": "John"}, output_path: "filled.pdf" }` |
| **Create blank PDF** | `Pdf { action: "create", output_path: "blank.pdf", pages: 2 }` |
| Add text to non-fillable PDF | `Pdf { action: "add_text", file_path: "doc.pdf", texts: [{"page": 1, "x": 100, "y": 500, "text": "Hello", "size": 12}], output_path: "out.pdf" }` |

### When to fall back to Python/Bash
- Converting PDF to images (requires pypdfium2)
- Extracting form structure from non-fillable PDFs (requires pdfplumber)
- OCR on scanned PDFs
- Advanced encryption/decryption (requires qpdf CLI)

For these cases, see REFERENCE.md and FORMS.md.

## Form Filling Workflow

### Fillable PDFs (have form fields)
```
Pdf { action: "get_form_fields", file_path: "form.pdf" }
# → returns field names and types
Pdf { action: "fill_form", file_path: "form.pdf", field_values: {"LastName": "Smith", "FirstName": "John"}, output_path: "filled.pdf" }
```

### Non-fillable PDFs (no form fields — use text annotations)
```
Pdf { action: "extract_text", file_path: "form.pdf" }
# → read the text to understand the layout
Pdf { action: "add_text", file_path: "form.pdf", texts: [
  {"page": 1, "x": 200, "y": 700, "text": "John Smith", "size": 10},
  {"page": 1, "x": 200, "y": 650, "text": "123 Main St", "size": 10}
], output_path: "filled.pdf" }
```

Coordinates are in PDF points (72 points per inch, y=0 is bottom of page).

## Quick Start (LEGACY — prefer Pdf tool above)

```python
from pypdf import PdfReader, PdfWriter

# Read a PDF
reader = PdfReader("document.pdf")
print(f"Pages: {len(reader.pages)}")

# Extract text
text = ""
for page in reader.pages:
    text += page.extract_text()
```

## Python Libraries

### pypdf - Basic Operations

#### Merge PDFs
```python
from pypdf import PdfWriter, PdfReader

writer = PdfWriter()
for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]:
    reader = PdfReader(pdf_file)
    for page in reader.pages:
        writer.add_page(page)

with open("merged.pdf", "wb") as output:
    writer.write(output)
```

#### Split PDF
```python
reader = PdfReader("input.pdf")
for i, page in enumerate(reader.pages):
    writer = PdfWriter()
    writer.add_page(page)
    with open(f"page_{i+1}.pdf", "wb") as output:
        writer.write(output)
```

#### Extract Metadata
```python
reader = PdfReader("document.pdf")
meta = reader.metadata
print(f"Title: {meta.title}")
print(f"Author: {meta.author}")
print(f"Subject: {meta.subject}")
print(f"Creator: {meta.creator}")
```

#### Rotate Pages
```python
reader = PdfReader("input.pdf")
writer = PdfWriter()

page = reader.pages[0]
page.rotate(90)  # Rotate 90 degrees clockwise
writer.add_page(page)

with open("rotated.pdf", "wb") as output:
    writer.write(output)
```

### pdfplumber - Text and Table Extraction

#### Extract Text with Layout
```python

From SeifBenayed/cloclo, MIT.

More from SeifBenayed/cloclo