End-to-end document processing for agentic workflows. Create, read, edit,
convert, and analyze documents across the five major office formats: PDF,
DOCX, XLSX, PPTX, and cross-format conversion.
Quick Reference
Task
Library/Tool
Key Command/Pattern
Extract text (simple)
pypdf
PdfReader("f.pdf").pages[0].extract_text()
Extract text (layout)
pdfplumber
pdf.pages[i].extract_text()
Extract tables
pdfplumber
pdf.pages[i].extract_tables()
Merge PDFs
pypdf
PdfWriter().append(…).write("out.pdf")
Split PDFs
pypdf
Write page slices to separate files
Rotate pages
pypdf
page.rotate(90)
Add watermark
pypdf
Overlay PDF onto target
Fill form fields
pypdf
update_page_form_field_values(page, data)
OCR scanned PDF
pytesseract + pdf2image
Convert to images → Tesseract
Create DOCX from scratch
python-docx
Document().add_heading(…)
Mail merge (template)
python-docx + CSV
Replace {{PLACEHOLDER}} in runs
DOCX → PDF
LibreOffice headless
soffice --headless --convert-to pdf
Create XLSX with charts
openpyxl
Workbook() → add BarChart()
Pivot table
openpyxl
PivotTable() on new sheet
XLSX → CSV
pandas
read_excel().to_csv()
Create PPTX
python-pptx
Presentation().slides.add_slide(…)
Speaker notes
python-pptx
slide.notes_slide.notes_text_frame.text
Cross-format convert
pandoc
pandoc input.docx -o output.md
Validate tools
doc_tools_check.py
Run at start of every session
When to Activate
Activate this skill when the user needs to do something with a document
as opposed to merely viewing it. Activation triggers include:
Trigger
Example phrasing
PDF manipulation
"extract pages from this PDF", "merge these PDFs", "fill out this form", "rotate page 3", "add a watermark", "OCR this scanned document", "split this PDF into chapters"
DOCX creation / editing
"write a report as a Word doc", "update the template", "mail-merge these names", "convert my markdown to DOCX", "generate an invoice as .docx"
XLSX spreadsheet work
"create a budget spreadsheet", "add a chart to the Excel file", "calculate column totals", "generate a pivot table", "format this data as a table"
PPTX presentation
"make a slide deck from these notes", "add speaker notes", "generate charts in PowerPoint", "create a presentation from this outline"
Format conversion
"convert PDF to DOCX", "turn this Word doc into Markdown", "XLSX to CSV", "DOCX to PDF", "PPTX to images"
Non-triggers (do NOT activate):
"Read this PDF to me" (pure text extraction for viewing — use a simpler read/extract path, not this full skill)
"Edit this paragraph" (general text editing, not document-format editing)
"What does this image look like?" (image analysis, not document processing)
"Summarise this article" (content summarisation, not document manipulation)
"Can you crop this photo?" (image editing, not document processing)
Common Pitfalls & Anti-Patterns
❌ NEVER do these
Overwriting the source file — you'll lose the original
Always write to {original}_processed.{ext} or {original}_{operation}.{ext}
If the user insists on overwrite, show both paths and confirm first
Forgetting to run doc_tools_check.py before operations
Missing libraries cause obscure errors. Run the checker first in every session.
Using pypdf for table extraction — it'll give you garbage
pypdf extracts raw text with no layout awareness. Use pdfplumber for tables and columnar text.
Loading a 500MB file entirely into memory
For large files (>100MB): use streaming/chunking. For PDFs >1,000 pages: extract page ranges.
Assuming cell.value returns a formatted string when it returns None
XLSX formulas return None unless you load with data_only=True. Even then, cached values may be stale.
Using hardcoded slide layout indices (prs.slide_layouts[0])
Layout order differs between templates. List dynamically: [ly.name for ly in prs.slide_layouts]
Running Pandoc without checking it's installed
Pandoc is a system dependency, not a Python package. brew install pandoc / apt install pandoc.
Trying to fill XFA (XML Forms Architecture) forms with pypdf
pypdf only handles AcroForm fields. XFA forms require different tools — check reader.get_fields() first.
Mixing document formats without checking conversion quality
PDF → DOCX conversion loses structure. DOCX → PDF via LibreOffice preserves it. Check references/conversion-matrix.md for quality ratings.
✅ Decision Matrix: Which Library When?
Outcome
PDF
DOCX
XLSX
PPTX
Simple text extraction
pypdf
N/A
N/A
N/A
Layout-aware text
pdfplumber
python-docx
openpyxl
python-pptx
Table extraction
pdfplumber
python-docx
openpyxl
N/A
Create from scratch
N/A
python-docx
openpyxl
python-pptx
Template filling
pypdf (forms)
python-docx
openpyxl
python-pptx
Charts
N/A
N/A
openpyxl
python-pptx
Images/OCR
pytesseract
python-docx
openpyxl
python-pptx
Conversion to other
LibreOffice
pandoc/LibreOffice
pandas/LibreOffice
LibreOffice
Safety Rules (Mandatory)
Never overwrite the source file. Always write output to a new path.
Default naming: {original_name}_processed.{ext} or
{original_name}_{operation}.{ext}.
Validate output integrity. After every write operation, read back the
output file and confirm:
The file exists and is non-empty.
Page / row / slide counts are correct.
Critical content (text, data, images) survived the operation.
Warn on destructive operations. If a user explicitly asks to overwrite
the source, confirm before proceeding. Show both paths and ask.
Handle missing dependencies gracefully. Run scripts/doc_tools_check.py
before any document operation. If a required library is missing, install it
(with user approval) or suggest the command.
Preserve metadata when possible. Author, creation date, and custom
properties should survive transformations unless the user explicitly asks
to strip them.
Respect file size limits. For files >100 MB, warn the user and suggest
streaming / chunking approaches. For PDFs >1,000 pages, use page-range
extraction instead of loading the entire document.
Pre-Flight: Tool Validation
Before any document operation, validate the tooling:
python3 scripts/doc_tools_check.py
The script checks for:
pypdf — PDF manipulation (merge, split, rotate, metadata)
pdfplumber — PDF text/table extraction with layout awareness
python-docx — DOCX read/write
openpyxl — XLSX read/write, formulas, charts
python-pptx — PPTX read/write, slide generation
pandoc — universal format conversion (CLI)
If a tool is missing, the script outputs the exact pip install or brew install command. Run it first in every document-processing session.
import pdfplumber
with pdfplumber.open("input.pdf") as pdf:
for i, page inenumerate(pdf.pages):
text = page.extract_text()
tables = page.extract_tables()
print(f"--- Page {i+1} ---")
print(text)
Merge example:
from pypdf import PdfWriter, PdfReader
writer = PdfWriter()
for path in ["doc1.pdf", "doc2.pdf", "doc3.pdf"]:
writer.append(path)
writer.write("merged_output.pdf")
# Validateassertlen(PdfReader("merged_output.pdf").pages) == expected_pages
Form filling example:
from pypdf import PdfReader, PdfWriter
reader = PdfReader("form.pdf")
writer = PdfWriter()
writer.append(reader)
fields = reader.get_fields()
# Show user available fields, collect values
writer.update_page_form_field_values(writer.pages[0], {
"Name": "Jane Doe",
"Date": "2026-05-28",
"Amount": "150.00"
})
writer.write("form_filled.pdf")
OCR example:
import pytesseract
from pdf2image import convert_from_path
images = convert_from_path("scanned.pdf", dpi=300)
text = "\n\n".join(pytesseract.image_to_string(img) for img in images)
withopen("scanned_ocr.txt", "w") as f:
f.write(text)
4. Common Issues & Remedies
Issue
Remedy
Encrypted PDF without password
Ask user for password; if unavailable, report and stop
Scanned PDF (image-only)
Use OCR path (pdf2image + pytesseract)
Corrupt PDF
Try pypdf.PdfReader(strict=False), or use mutool repair
Extracted text is garbled
Use pdfplumber instead of pypdf for layout-aware extraction
Form fields not found
Check reader.get_fields() — some PDFs use XFA forms (unsupported)
Workflow: DOCX Creation & Editing
1. Decide: Template or Blank
Template approach: Start from an existing .docx with placeholders like
{{NAME}}, {{DATE}}, {{AMOUNT}}. Best for reports, invoices, letters.
Blank approach: Build from Document() using python-docx. Best for
simple documents or when no template exists.
2. Template Pattern
from docx import Document
doc = Document("template.docx")
# Replace placeholders across all paragraphs, tables, headers, footers
placeholders = {
"{{NAME}}": "Jane Doe",
"{{DATE}}": "28 May 2026",
"{{AMOUNT}}": "€1,500.00"
}
defreplace_in_paragraphs(paragraphs):
for para in paragraphs:
for key, val in placeholders.items():
if key in para.text:
for run in para.runs:
if key in run.text:
run.text = run.text.replace(key, val)
replace_in_paragraphs(doc.paragraphs)
for table in doc.tables:
for row in table.rows:
for cell in row.cells:
replace_in_paragraphs(cell.paragraphs)
for section in doc.sections:
replace_in_paragraphs(section.header.paragraphs)
replace_in_paragraphs(section.footer.paragraphs)
doc.save("output.docx")
3. Building from Scratch
from docx import Document
from docx.shared import Inches, Pt, Cm, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.enum.table import WD_TABLE_ALIGNMENT
doc = Document()
# Styles
style = doc.styles['Normal']
style.font.name = 'Calibri'
style.font.size = Pt(11)
# Heading
doc.add_heading('Quarterly Report', level=1)
# Paragraph
p = doc.add_paragraph('Executive summary of Q1 2026 results.')
p.alignment = WD_ALIGN_PARAGRAPH.LEFT
# Bold run
run = p.add_run(' Key highlights:')
run.bold = True# Bullet listfor item in ['Revenue up 12%', 'Costs down 4%', '3 new markets entered']:
doc.add_paragraph(item, style='List Bullet')
# Table
table = doc.add_table(rows=3, cols=3, style='Light Grid Accent 1')
table.alignment = WD_TABLE_ALIGNMENT.CENTER
data = [['Metric', 'Q4 2025', 'Q1 2026'],
['Revenue', '€2.1M', '€2.35M'],
['Profit', '€420K', '€510K']]
for i, row_data inenumerate(data):
for j, cell_val inenumerate(row_data):
table.rows[i].cells[j].text = cell_val
# Image
doc.add_picture('chart.png', width=Inches(5.5))
doc.save('report.docx')
4. Mail Merge for Bulk Documents
from docx import Document
import csv
doc = Document("letter_template.docx")
withopen("recipients.csv") as f:
recipients = list(csv.DictReader(f))
for i, recipient inenumerate(recipients):
doc_copy = Document("letter_template.docx")
for para in doc_copy.paragraphs:
for key, val in recipient.items():
iff"{{{{{key}}}}}"in para.text:
for run in para.runs:
run.text = run.text.replace(f"{{{{{key}}}}}", val)
doc_copy.save(f"letter_{i+1:03d}.docx")
import openpyxl
from openpyxl.utils import get_column_letter
wb = openpyxl.load_workbook("data.xlsx", data_only=True)
ws = wb.active
print(f"Sheet: {ws.title}, Rows: {ws.max_row}, Cols: {ws.max_column}")
# Read headers
headers = [cell.value for cell in ws[1]]
print(f"Columns: {headers}")
# Read all data as list of dicts
data = []
for row in ws.iter_rows(min_row=2, values_only=True):
data.append(dict(zip(headers, row)))
from pptx import Presentation
import json
prs = Presentation("template.pptx")
withopen("slide_content.json") as f:
content = json.load(f)
for slide_data in content["slides"]:
slide = prs.slides.add_slide(
prs.slide_layouts[slide_data["layout_index"]]
)
slide.shapes.title.text = slide_data["title"]
if"body"in slide_data:
slide.placeholders[1].text = slide_data["body"]
prs.save("generated_deck.pptx")
4. PPTX Common Issues
Issue
Fix
Layout index not found
List available: [ly.name for ly in prs.slide_layouts]
Placeholder missing
Check slide.placeholders; not all layouts have placeholder[1]
Images too large
Resize with PIL first, or use Inches() to set exact dimensions
Font not available on system
Use common fonts (Calibri, Arial) or embed fonts
Workflow: Format Conversion
The Conversion Matrix
See references/conversion-matrix.md for the full cross-reference. Quick
reference for the most common paths:
From
To
Tool
Quality
DOCX
PDF
LibreOffice headless
⭐⭐⭐⭐⭐ Best
DOCX
Markdown
pandoc -i input.docx -o output.md
⭐⭐⭐⭐ Good
Markdown
DOCX
pandoc -i input.md -o output.docx
⭐⭐⭐⭐ Good
Markdown
PDF
pandoc --pdf-engine=xelatex
⭐⭐⭐⭐⭐ Best
PDF
DOCX
pdf2docx library or LibreOffice
⭐⭐⭐ Moderate
PDF
Text
pdfplumber or pandoc
⭐⭐⭐⭐ Good
XLSX
CSV
pandas.read_excel().to_csv()
⭐⭐⭐⭐⭐ Lossless
XLSX
PDF
LibreOffice headless
⭐⭐⭐⭐ Good
PPTX
PDF
LibreOffice headless
⭐⭐⭐⭐ Good
PPTX
Images
pptx → PDF → pdf2image
⭐⭐⭐ Moderate
HTML
DOCX
pandoc -i input.html -o output.docx
⭐⭐⭐ Moderate
Generic Pandoc Pattern
# Basic conversion
pandoc input.docx -o output.md
# With template and metadata
pandoc input.md \
--template=corporate.latex \
--metadata title="Q1 Report" \
--metadata author="Jane Doe" \
--pdf-engine=xelatex \
-o output.pdf
# Convert with reference document for styling
pandoc input.md --reference-doc=styles.docx -o output.docx
# Batch conversionfor file in *.md; do
pandoc "$file" -o "${file%.md}.docx"done
PDF → DOCX (Best Available)
# Using pdf2docx (best fidelity for text-heavy PDFs)from pdf2docx import Converter
cv = Converter("input.pdf")
cv.convert("output.docx", start=0, end=None)
cv.close()
# Fallback: extract text, rebuild in python-docximport pdfplumber
from docx import Document
doc = Document()
with pdfplumber.open("input.pdf") as pdf:
for page in pdf.pages:
text = page.extract_text()
if text:
doc.add_paragraph(text)
doc.save("output.docx")
XLSX → CSV / JSON
import pandas as pd
df = pd.read_excel("data.xlsx", sheet_name=None) # All sheetsfor sheet_name, sheet_df in df.items():
sheet_df.to_csv(f"data_{sheet_name}.csv", index=False)
sheet_df.to_json(f"data_{sheet_name}.json", orient="records")
Platform Compatibility Notes
Claude Code / Codex
Full Python scripting capability — all libraries available.
Use subprocess for pandoc and LibreOffice calls.
Recommend pip install for missing packages.
Cursor
Works identically; execute scripts via integrated terminal.
Use the doc_tools_check.py script as a pre-commit or task runner.
Gemini CLI
Can execute Python but may have restricted subprocess access.
Prefer pure-Python libraries (pypdf, pdfplumber, python-docx, openpyxl,
python-pptx) over CLI tools when possible.
Pandoc may not be available; fall back to Python-only conversion paths.
OpenClaw
Full tool access. Can install packages and run both Python scripts and
external CLI tools.
Recommended: run doc_tools_check.py on first invocation to set up the
environment.
GitHub Copilot
Chat context; provide complete, self-contained Python snippets.
Include dependency installation comments.
Tip: reference scripts/doc_tools_check.py for the install list.
Windsurf
Full Python execution in IDE terminal; all libraries supported.
Use doc_tools_check.py for environment validation.
Store reusable template files in project workspace.
OpenCode
Execute scripts via terminal with full Python access.
Prefer pure-Python libraries for portability.
Run doc_tools_check.py to validate environment before any operation.
Integration Pattern
A typical document-processing session follows this sequence:
