---

name: pdf description: Read, create, edit, and annotate PDFs; extract text/tables; fill forms; and manage PDF comments. Use when users mention PDFs, forms, annotations, merge/split, or PDF extraction.

PDF Reading, Creation, and Editing

Overview

Prefer *_parsed/ markdown for search and citations. Use pdfplumber for fallback text/table extraction. Use pypdf for merge/split.

Reading PDFs

If *_parsed/ folder exists (preferred)

Most PDFs are parsed into a sibling folder like MyFile_parsed/.

Copyrg "search term" /root/workspace/MyFile_parsed/
cat /root/workspace/MyFile_parsed/page_3.md

If no *_parsed/ folder

Text extraction (fallback):

Copyimport pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    for page in pdf.pages:
        print(page.extract_text() or "")

Table extraction (common in CMC/clinical PDFs):

Copyimport pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    for page in pdf.pages:
        for table in page.extract_tables():
            for row in table:
                print(row)

Editing PDFs (Common Operations)

Merge PDFs (eCTD packaging, combining appendices)

Copyfrom pypdf import PdfReader, PdfWriter

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

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

Split PDF (extract specific pages)

Copyfrom pypdf import PdfReader, PdfWriter

reader = PdfReader("input.pdf")

# Example: write pages 1-3 (0-based indices 0..2)
writer = PdfWriter()
for page in reader.pages[0:3]:
    writer.add_page(page)

with open("pages_1_to_3.pdf", "wb") as out:
    writer.write(out)

Form Filling (Regulatory Forms)

PDF form filling is a common regulated workflow (e.g., submissions/admin forms).

Step 1: Check if the PDF is fillable

Copypython /root/skills/pdf/scripts/check_fillable_fields.py file.pdf

If fillable fields exist

1. Extract field IDs and metadata:

Copypython /root/skills/pdf/scripts/extract_form_field_info.py input.pdf field_info.json

1. Create field_values.json:

Copy[
  {"field_id": "last_name", "page": 1, "value": "Simpson"},
  {"field_id": "checkbox1", "page": 1, "value": "/On"}
]

1. Fill (edits in place):

Copypython /root/skills/pdf/scripts/fill_fillable_fields.py file.pdf field_values.json

If not fillable (annotation-based)

This is more manual (you need bounding boxes). Use the detailed guide:

• forms.md

High-level flow:

• Convert pages to images → define bounding boxes → validate → fill with annotations.

Visual Verification (when layout matters)

After each meaningful update—content, layout, or style—render to images and inspect:

Copypdftoppm -png file.pdf /root/tmp/preview
# Then call: view { path: "/root/tmp/preview-1.png" }

Inspect every affected page. If anything looks off (clipped text, overlaps, broken tables), fix the source and re-render until clean.

Creating PDFs

Use reportlab for programmatic PDF creation:

Copyfrom reportlab.lib.pagesizes import letter
from reportlab.platypus import SimpleDocTemplate, Paragraph, Table
from reportlab.lib.styles import getSampleStyleSheet

doc = SimpleDocTemplate('/root/workspace/output.pdf', pagesize=letter)
styles = getSampleStyleSheet()
story = []

story.append(Paragraph('Report Title', styles['Title']))
story.append(Paragraph('Body content here.', styles['Normal']))

data = [['Header 1', 'Header 2'], ['Row 1', 'Data']]
story.append(Table(data))

doc.build(story)

After creating: Render to PNG and verify layout before finalizing. Fix any clipped text, overlapping elements, or alignment issues, then re-render until clean. Save the PDF under /root/workspace so it syncs automatically.

Command-Line Tools

Copy# Merge PDFs
qpdf --empty --pages doc1.pdf doc2.pdf -- merged.pdf

# Extract pages 1-5
qpdf input.pdf --pages . 1-5 -- pages1-5.pdf

# Extract text (preserving layout)
pdftotext -layout input.pdf output.txt

OCR for Scanned PDFs

Copyimport pytesseract
from pdf2image import convert_from_path

images = convert_from_path('scanned.pdf')
for i, image in enumerate(images):
    text = pytesseract.image_to_string(image)
    print(f"Page {i+1}:\n{text}")

Document Review (Annotations)

PyMuPDF enables AI agents to act as document reviewers—adding comments, highlights, stamps, and managing existing annotations.

Add Comments (Sticky Notes)

1. Create a comments.json file:

Copy[
  {
    "id": "CMT-001",
    "page": 3,
    "section": "2. PROJECT SPECIFICATIONS",
    "text": "Consider adding a dedicated list of applicable standards.",
    "severity": "Major",
    "status": "Open"
  },
  {
    "page": 5,
    "section": "4. SURFACE PREPARATION",
    "text": "Suggest stating acceptable initial rust grades.",
    "severity": "Minor",
    "status": "Pending",
    "search_terms": ["SURFACE PREPARATION", "surface prep", "blast cleaning"]
  }
]

1. Run the script (edits in place):

Copypython /root/skills/pdf/scripts/add_comments.py file.pdf comments.json

Options: --author "Name", --auto-position, --skip-pages N, --no-summary

• Severity: Critical, Major (red), Minor (orange), Info (blue)
• Status: Open, Pending, Accepted, Rejected, Closed
• IDs: Auto-generated (e.g., CMT-A1B2C3D4) if not provided

List Annotations

Copy# List all annotations as JSON
python /root/skills/pdf/scripts/manage_annotations.py list input.pdf

# Summary only
python /root/skills/pdf/scripts/manage_annotations.py list input.pdf --summary

# Export to file
python /root/skills/pdf/scripts/manage_annotations.py list input.pdf -o annotations.json

Delete Annotations (edits in place)

Copy# Delete all annotations
python /root/skills/pdf/scripts/manage_annotations.py delete file.pdf --all

# Delete by specific ID
python /root/skills/pdf/scripts/manage_annotations.py delete file.pdf --by-id CMT-A1B2C3D4

# Delete by status (e.g., remove resolved comments)
python /root/skills/pdf/scripts/manage_annotations.py delete file.pdf --by-status Closed

# Delete by author
python /root/skills/pdf/scripts/manage_annotations.py delete file.pdf --by-author "John"

# Delete by type (Text, Highlight, FreeText, Stamp, etc.)
python /root/skills/pdf/scripts/manage_annotations.py delete file.pdf --by-type Text

Update Comment Status (edits in place)

Copy# Mark a comment as closed/resolved
python /root/skills/pdf/scripts/manage_annotations.py update file.pdf --id CMT-A1B2C3D4 --status Closed

# Mark as accepted
python /root/skills/pdf/scripts/manage_annotations.py update file.pdf --id CMT-A1B2C3D4 --status Accepted

Status changes update the annotation color: Closed/Accepted → green, Rejected → gray.

Add Highlights, Strikethroughs, Stamps (edits in place)

Copy# Highlight text on a page
python /root/skills/pdf/scripts/manage_annotations.py highlight file.pdf -p 3 -t "important text"

# Strikethrough text (for deletions/corrections)
python /root/skills/pdf/scripts/manage_annotations.py strikethrough file.pdf -p 3 -t "remove this"

# Add approval stamp
python /root/skills/pdf/scripts/manage_annotations.py stamp file.pdf -p 1 -t Approved
# Stamp types: Approved, NotApproved, Draft, Final, Confidential, Void, ForComment, Preliminary, etc.

Limitations

• No track changes: PDFs don't support Word-style revision marks. Use strikethroughs + comments to simulate.
• No comment replies: PDF annotations don't have native threading. Use numbered comments with references.
• No accept/reject: Changes must be made by editing the source document (Word/LaTeX) or using annotation overlays.

Quality Expectations

• No AI citation tokens: Never include [145036110387964†L158-L160] or 【turn...】 in output documents
• No Unicode issues: Use ASCII hyphens, not special Unicode dashes
• No rendering issues: Check for clipped text, overlapping elements

References

• forms.md - detailed form-filling (incl. annotation-based)
• reference.md - advanced PDF troubleshooting and libraries
• /root/skills/pdf/scripts/add_comments.py - add review comments as sticky notes
• /root/skills/pdf/scripts/manage_annotations.py - list, delete, highlight, stamp annotations