Agent skill
pdf-editing
Complete guide for reading and editing PDF documents with PyMuPDF.
Install this agent skill to your Project
npx add-skill https://github.com/benchflow-ai/skillsbench/tree/main/tasks/edit-pdf/environment/skills/pdf-editing
SKILL.md
PDF Editing Skill
CRITICAL RULES - READ FIRST
NEVER DO THESE:
- NEVER use strikethrough lines to cross out text
- NEVER rasterize or flatten the PDF to images
- NEVER convert PDF pages to PNG/JPG and draw on them
- NEVER use pdf-to-image-to-pdf workflows
- NEVER use add_redact_annot() with BLACK fill (use WHITE fill instead)
- NEVER add text NEXT TO old values - REPLACE them at the SAME position
TWO APPROACHES - CHOOSE THE RIGHT ONE:
-
For REPLACING text (e.g., updating name, email, DOB):
- Use
draw_rect()with white fill to cover old text - Use
insert_text()at the SAME position - Text layer is preserved
- Use
-
For TRUE REDACTION of sensitive data (e.g., student ID):
- Use
add_redact_annot(rect, fill=(1,1,1))with WHITE fill - Call
apply_redactions()to REMOVE text from PDF structure - Then
insert_text()to add masked value (e.g., "****5678") - Original text is completely removed, not just covered
- Use
Overview
USE PYTHON WITH PyMuPDF (fitz) - it is pre-installed and produces the best results.
PyMuPDF preserves the text layer properly, making text extractable after editing. JavaScript libraries like pdf-lib may create text that tools like pypdf cannot extract.
# PyMuPDF is already installed - just use it
python3 -c "import fitz; print('PyMuPDF ready')"
Reading PDF Content
import fitz
doc = fitz.open("input.pdf")
page = doc[0]
# Extract all text to understand the document
text = page.get_text()
print(text)
Finding Text Positions
# search_for() returns list of rectangles where text is found
rects = page.search_for("Label Text")
if rects:
rect = rects[0]
# rect.x0, rect.y0 = top-left corner
# rect.x1, rect.y1 = bottom-right corner
print(f"Found at: ({rect.x0}, {rect.y0}) to ({rect.x1}, {rect.y1})")
Inserting Text
# Insert text at a specific position
page.insert_text(
(x_position, y_position), # coordinates
"text to insert",
fontsize=11,
color=(0, 0, 0) # black
)
doc.save("output.pdf")
Common Pattern: Fill Empty Form Fields
When a form field is empty (no existing value), insert text next to the label:
import fitz
doc = fitz.open("input.pdf")
page = doc[0]
# Find label, insert value to the right of it
label_rect = page.search_for("FIELD LABEL:")[0]
page.insert_text((label_rect.x1 + 5, label_rect.y1), "value", fontsize=11)
# For today's date
from datetime import datetime
date_rect = page.search_for("Date")[0]
today = datetime.now().strftime("%Y/%m/%d")
page.insert_text((date_rect.x1 + 5, date_rect.y1), today, fontsize=11)
# For signatures - insert the person's name
sig_rect = page.search_for("signature")[0]
page.insert_text((sig_rect.x1 + 5, sig_rect.y1), "Full Name", fontsize=12)
doc.save("output.pdf")
Replacing Existing Text (CRITICAL - MUST FOLLOW)
When you need to replace text that's already in the PDF with new/correct values:
- First extract the PDF text to see what's currently there
- Compare with the correct values from your input source
- For any value that needs to change: COVER with white rectangle, then insert new text AT THE SAME POSITION
WRONG vs RIGHT approaches:
WRONG - DO NOT DO THIS:
# WRONG: Adding text next to old value
page.insert_text((old_rect.x1 + 10, old_rect.y1), new_value) # NO!
# WRONG: Using strikethrough
page.draw_line(start, end, color=(0,0,0)) # NO!
# WRONG: Rasterizing to image
pix = page.get_pixmap() # NO! Destroys text layer
RIGHT - DO THIS:
import fitz
doc = fitz.open("input.pdf")
page = doc[0]
# First, extract text to see what's in the PDF
current_text = page.get_text()
print(current_text) # Examine what values exist
# To replace a value you found that needs changing:
old_value = "..." # The value you found in the PDF that's wrong
new_value = "..." # The correct value from your input source
rects = page.search_for(old_value)
if rects:
rect = rects[0]
# STEP 1: Draw WHITE rectangle to COMPLETELY COVER old text
page.draw_rect(rect, color=(1, 1, 1), fill=(1, 1, 1), width=0)
# STEP 2: Insert new text at the SAME position (not offset!)
page.insert_text((rect.x0, rect.y1), new_value, fontsize=11, color=(0, 0, 0))
doc.save("output.pdf")
Key points:
draw_rect(rect, fill=(1,1,1), width=0)draws a WHITE filled rectangle(1, 1, 1)is white in RGB (0-1 scale)- Insert new text at
rect.x0(same X position), NOTrect.x1 + offset - The old text becomes invisible under the white rectangle
- The new text appears in the same location
- Text layer is preserved (text remains extractable)
TRUE REDACTION for Sensitive Data (IMPORTANT!)
For sensitive data like student IDs, you must use TRUE REDACTION that removes the original text from the PDF structure. A white rectangle only VISUALLY covers text - tools like pypdf can still extract the hidden text!
CRITICAL DISTINCTION:
draw_rect()= Visual cover only (text still extractable by machines)add_redact_annot()+apply_redactions()= TRUE redaction (text removed from PDF)
Example: "A12345678" should become "****5678" (show only last 4 digits)
import fitz
doc = fitz.open("input.pdf")
page = doc[0]
# 1. First find what value is in the PDF by reading the text
pdf_text = page.get_text()
# Find the ID in the text (e.g., "A88888888")
original_in_pdf = "A88888888" # Value you found in the PDF
# Extract just the digits for masking
digits = ''.join(c for c in original_in_pdf if c.isdigit())
masked = "****" + digits[-4:] # Result: "****8888"
rects = page.search_for(original_in_pdf)
if rects:
rect = rects[0]
# STEP 1: Create TIGHT bounding box to avoid covering nearby labels
tight_rect = fitz.Rect(rect.x0, rect.y0 + 8, rect.x1, rect.y1 - 2)
# STEP 2: Add redaction annotation with WHITE fill (not black!)
page.add_redact_annot(tight_rect, fill=(1, 1, 1)) # WHITE fill
# STEP 2: Apply redactions - this REMOVES the text from PDF structure
page.apply_redactions()
# STEP 3: Insert masked value at the same position
page.insert_text((rect.x0, rect.y1), masked, fontsize=11, color=(0, 0, 0))
doc.save("output.pdf")
Why this works:
add_redact_annot(rect, fill=(1, 1, 1))- marks area with WHITE rectangleapply_redactions()- REMOVES the underlying text from PDF structureinsert_text()- adds the masked value
WRONG approaches:
# WRONG: Black box redaction (ugly and suspicious)
page.add_redact_annot(rect, fill=(0, 0, 0)) # NO! Use white fill
# WRONG: Only using draw_rect (text still extractable!)
page.draw_rect(rect, fill=(1, 1, 1)) # NO! This only covers visually
page.insert_text(...) # Original text is still in PDF structure!
# WRONG: Adding masked value NEXT TO original
page.insert_text((rect.x1 + 10, rect.y1), masked) # NO!
Workflow: Compare and Update
import fitz
doc = fitz.open("input.pdf")
page = doc[0]
# Step 1: Read PDF to see current content
pdf_text = page.get_text()
print(pdf_text)
# Step 2: Read your input source to get correct values
# (parse input file, extract the values you need)
# Step 3: For each value that differs, replace it
# Build a dict of {old_value_in_pdf: correct_value}
replacements = {} # Populate by comparing PDF content with correct values
for old_val, new_val in replacements.items():
if old_val == new_val:
continue # Skip if already correct
rects = page.search_for(old_val)
if rects:
rect = rects[0]
# Cover old text with white rectangle
page.draw_rect(rect, color=(1, 1, 1), fill=(1, 1, 1), width=0)
# Insert new text
page.insert_text((rect.x0, rect.y1), new_val, fontsize=11, color=(0, 0, 0))
doc.save("output.pdf")
Important Guidelines
- COVER then REPLACE - Use white rectangle to cover old text, insert new text at SAME position
- Never use strikethrough - No lines through text, no crossing out
- Never rasterize - No converting PDF to images, no get_pixmap() workflows
- Never add text NEXT TO old values - Replace AT the same position
- Never use add_redact_annot() with black - It creates black boxes
- Preserve all labels - Form labels should remain visible
- Preserve text layer - Text must remain extractable after editing
- Match font size - Typically 10-12pt for forms
Alternative: JavaScript with pdf-lib (NOT RECOMMENDED)
WARNING: pdf-lib may create text that cannot be extracted by pypdf. Use Python with PyMuPDF instead whenever possible.
If you must use Node.js/JavaScript, use pdf-lib with the same approach:
const { PDFDocument, rgb } = require('pdf-lib');
const fs = require('fs');
async function editPdf() {
const pdfBytes = fs.readFileSync('input.pdf');
const pdfDoc = await PDFDocument.load(pdfBytes);
const page = pdfDoc.getPages()[0];
const { height } = page.getSize();
// To replace text at known coordinates:
// STEP 1: Draw WHITE rectangle to cover old text
page.drawRectangle({
x: oldTextX,
y: oldTextY,
width: oldTextWidth,
height: oldTextHeight,
color: rgb(1, 1, 1), // WHITE
});
// STEP 2: Draw new text at the SAME position
page.drawText('New Value', {
x: oldTextX, // SAME X position, not offset!
y: oldTextY,
size: 11,
color: rgb(0, 0, 0),
});
fs.writeFileSync('output.pdf', await pdfDoc.save());
}
WRONG with pdf-lib:
// WRONG: Adding text to the right of old value
page.drawText('New Value', {
x: oldTextX + oldTextWidth + 10, // NO! Don't offset
...
});
// WRONG: Drawing strikethrough line
page.drawLine({
start: { x: x1, y: y },
end: { x: x2, y: y },
color: rgb(0, 0, 0), // NO strikethrough!
});
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
csv-processing
Use this skill when reading sensor data from CSV files, writing simulation results to CSV, processing time-series data with pandas, or handling missing values in datasets.
pid-controller
Use this skill when implementing PID control loops for adaptive cruise control, vehicle speed regulation, throttle/brake management, or any feedback control system requiring proportional-integral-derivative control.
yaml-config
Use this skill when reading or writing YAML configuration files, loading vehicle parameters, or handling config file parsing with proper error handling.
simulation-metrics
Use this skill when calculating control system performance metrics such as rise time, overshoot percentage, steady-state error, or settling time for evaluating simulation results.
vehicle-dynamics
Use this skill when simulating vehicle motion, calculating safe following distances, time-to-collision, speed/position updates, or implementing vehicle state machines for cruise control modes.
web-interface-guidelines
Vercel's comprehensive UI guidelines for building accessible, performant web interfaces. Use this skill when reviewing or building UI components for compliance with best practices around accessibility, performance, animations, and visual stability.
Didn't find tool you were looking for?