seb1n/awesome-ai-agent-skills / documents-and-files/pdf-processing
pdf-processing
VerifiedInspect, extract, OCR, create, merge, split, reorder, rotate, annotate, fill, redact, compress, secure, and verify PDF documents while preserving source files and visual fidelity. Use when working with one or more .pdf files; converting documents to or from PDF; extracting text, tables, images, metadata, forms, or page ranges; applying true redactions or signatures; diagnosing malformed, encrypted, scanned, or inaccessible PDFs; or validating that a PDF transformation preserved the intended content and layout.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.7 KB |
| agents/openai.yaml | config | 215 B |
| assets/processing-record-template.md | markdown | 1.0 KB |
| references/tool-routing.md | markdown | 3.0 KB |
| references/verification-checklist.md | markdown | 2.6 KB |
| scripts/inspect_pdf.pyexecutable | script | 12.6 KB |
scripts/inspect_pdf.py
View on GitHub#!/usr/bin/env python3
"""Inspect PDF structure without modifying or activating document content.
The default mode uses byte-level heuristics only. --deep may invoke an installed
PDF parser or pdfinfo. Untrusted inputs require a separately verified sandbox.
"""
from __future__ import annotations
import argparse
import hashlib
import importlib.util
import json
import os
from pathlib import Path
import re
import shutil
import stat
import subprocess
import sys
import tempfile
from typing import Any, Iterable
ACTIVE_MARKERS = {
"javascript": rb"/JavaScript\b|/JS\b",
"open_action": rb"/OpenAction\b",
"additional_actions": rb"/AA\b",
"launch_action": rb"/Launch\b",
"embedded_files": rb"/EmbeddedFiles\b|/Filespec\b",
"rich_media": rb"/RichMedia\b|/Movie\b|/Sound\b",
"acroform": rb"/AcroForm\b",
"xfa": rb"/XFA\b",
}
TOOL_NAMES = ("pdfinfo", "pdftotext", "pdftoppm", "qpdf", "mutool", "gs", "ocrmypdf", "tesseract", "verapdf")
MODULE_NAMES = ("pypdf", "PyPDF2", "fitz", "pdfplumber")
MAX_RAW_SCAN_BYTES = 100_000_000
class OutputPathError(Exception):
"""Raised when a report destination could overwrite the inspected input."""
def lexical_path(path: Path) -> Path:
return Path(os.path.abspath(os.path.normpath(os.fspath(path))))
def resolved_path(path: Path) -> Path:
try:
return path.resolve(strict=False)
except (OSError, RuntimeError) as exc:
raise OutputPathError(f"cannot resolve path safely: {path}: {exc}") from exc
def validate_output_path(output: Path, inputs: Iterable[Path]) -> Path:
output_lexical = lexical_path(output)
output_resolved = resolved_path(output)
try:
output_stat = output.lstat()
except FileNotFoundError:
output_exists = False
except OSError as exc:
raise OutputPathError(f"cannot inspect output path: {output}: {exc}") from exc
else:
output_exists = True
if not stat.S_ISREG(output_stat.st_mode):
raise OutputPathError(f"output exists and is not a regular file: {output}")
for source in inputs:
if output_lexical == lexical_path(source) or output_resolved == resolved_path(source):
raise OutputPathError(f"output aliases an input path: {output}")
if output_exists and source.exists():
try:
if os.path.samefile(output, source):
raise OutputPathError(f"output aliases an input inode: {output}")
except OutputPathError:
raise
except OSError as exc:
raise OutputPathError(
f"cannot safely compare output and input paths: {output}: {exc}"
) from exc
parent = output_lexical.parent
if not parent.exists():
raise OutputPathError(f"output directory does not exist: {parent}")
if not parent.is_dir():
raise OutputPathError(f"output parent is not a directory: {parent}")
return output_resolved
def atomic_write_text(output: Path, payload: str, inputs: Iterable[Path]) -> None:
input_paths = tuple(inputs)
destination = validate_output_path(output, input_paths)
parent = destination.parent
temp_path: Path | None = None
try:
file_descriptor, temp_name = tempfile.mkstemp(
prefix=f".{output.name}.", suffix=".tmp", dir=parent
)
temp_path = Path(temp_name)
with os.fdopen(file_descriptor, "w", encoding="utf-8", newline="") as handle:
handle.write(payload)
handle.flush()
os.fsync(handle.fileno())
destination = validate_output_path(output, input_paths)
if destination.parent != parent:
raise OutputPathError(f"output directory changed during write: {output.parent}")
os.replace(temp_path, destination)
temp_path = None
except OutputPathError:
raise
except OSError as exc:
raise OutputPathError(f"unable to write output atomically: {output}: {exc}") from exc
finally:
if temp_path is not None:
try:
temp_path.unlink()
except FileNotFoundError:
pass
except OSError:
pass
def sha256(path: Path) -> str:
digest = hashlib.sha256()
with path.open("rb") as handle:
for chunk in iter(lambda: handle.read(1024 * 1024), b""):
digest.update(chunk)
return digest.hexdigest()
def raw_inspection(path: Path) -> dict[str, Any]:
size = path.stat().st_size
with path.open("rb") as handle:
data = handle.read(MAX_RAW_SCAN_BYTES)
if size > 4096:
handle.seek(-4096, 2)
else:
handle.seek(0)
tail = handle.read()
scan_complete = len(data) == size
header_match = re.search(rb"%PDF-(\d\.\d)", data[:1024])
page_objects = len(re.findall(rb"/Type\s*/Page(?!s)\b", data))
pages_nodes = len(re.findall(rb"/Type\s*/Pages\b", data))
eof_near_end = b"%%EOF" in tail
startxref_near_end = b"startxref" in tail
incremental_updates = max(0, len(re.findall(rb"%%EOF", data)) - 1)
markers = {
name: len(re.findall(pattern, data))
for name, pattern in ACTIVE_MARKERS.items()
}
warnings: list[str] = []
if not header_match:
warnings.append("No PDF header was found in the first 1024 bytes.")
if not eof_near_end:
warnings.append("No %%EOF marker was found in the final 4096 bytes.")
if not startxref_near_end:
warnings.append("No startxref marker was found in the final 4096 bytes.")
if not scan_complete:
warnings.append(
f"Feature and page-object scanning was limited to the first {MAX_RAW_SCAN_BYTES} bytes; later objects were not inspected."
)
if incremental_updates:
warnings.append("Multiple EOF markers suggest incremental revisions; old content may remain in the file.")
if any(markers[name] for name in ("javascript", "open_action", "additional_actions", "launch_action", "embedded_files", "rich_media")):
warnings.append("Potential active or embedded content markers are present; do not activate them during review.")
if b"/Encrypt" in data:
warnings.append("An encryption dictionary marker is present; content and permissions may require a password.")
return {
"header_version": header_match.group(1).decode("ascii") if header_match else None,
"eof_near_end": eof_near_end,
"startxref_near_end": startxref_near_end,
"page_count": page_objects if page_objects else None,
"page_count_method": "raw /Type /Page object count (heuristic)",
"bytes_scanned_for_objects": len(data),
"object_scan_complete": scan_complete,
"pages_tree_nodes": pages_nodes,
"encrypted_marker": b"/Encrypt" in data,
"linearized_marker": b"/Linearized" in data[:4096],
"incremental_update_markers": incremental_updates,
"feature_markers": markers,
"warnings": warnings,
}
def parser_inventory() -> dict[str, Any]:
return {
"commands": {name: shutil.which(name) for name in TOOL_NAMES},
"python_modules": {name: importlib.util.find_spec(name) is not None for name in MODULE_NAMES},
}
def deep_with_pypdf(path: Path) -> tuple[dict[str, Any] | None, str | None]:
reader_class = None
parser_name = None
try:
from pypdf import PdfReader # type: ignore
reader_class = PdfReader
parser_name = "pypdf"
except ImportError:
try:
from PyPDF2 import PdfReader # type: ignore
reader_class = PdfReader
parser_name = "PyPDF2"
except ImportError:
return None, "Neither pypdf nor PyPDF2 is installed."
try:
reader = reader_class(str(path), strict=False)
encrypted = bool(reader.is_encrypted)
result: dict[str, Any] = {
"method": parser_name,
"encrypted": encrypted,
"page_count": None,
"metadata_keys": [],
}
if not encrypted:
result["page_count"] = len(reader.pages)
metadata = reader.metadata or {}
result["metadata_keys"] = sorted(str(key) for key in metadata.keys())
return result, None
except Exception as exc: # Parser errors must be reported, not hidden.
return None, f"{parser_name} could not parse the file: {type(exc).__name__}: {exc}"
def deep_with_pdfinfo(path: Path) -> tuple[dict[str, Any] | None, str | None]:
executable = shutil.which("pdfinfo")
if not executable:
return None, "pdfinfo is not installed."
try:
completed = subprocess.run(
[executable, str(path)],
check=False,
capture_output=True,
text=True,
timeout=30,
)
except (OSError, subprocess.TimeoutExpired) as exc:
return None, f"pdfinfo failed: {type(exc).__name__}: {exc}"
fields: dict[str, str] = {}
for line in completed.stdout.splitlines():
if ":" in line:
key, value = line.split(":", 1)
fields[key.strip().lower().replace(" ", "_")] = value.strip()
result = {
"method": "pdfinfo",
"exit_code": completed.returncode,
"fields": fields,
}
error = completed.stderr.strip() or None
return result, error
def parse_args() -> argparse.Namespace:
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("pdf", type=Path, help="PDF file to inspect read-only")
parser.add_argument("--deep", action="store_true", help="Also invoke an installed parser/pdfinfo")
parser.add_argument(
"--trust-level", choices=("untrusted", "trusted"), default="untrusted",
help="Input trust decision; defaults to untrusted",
)
parser.add_argument(
"--sandbox-profile-confirmed", action="store_true",
help="Confirm the documented no-network/no-active-content sandbox profile before deep parsing untrusted input",
)
parser.add_argument(
"--output", type=Path,
help="Atomically write JSON to a regular file; input aliases are refused",
)
parser.add_argument("--pretty", action="store_true", help="Indent JSON output")
return parser.parse_args()
def main() -> int:
args = parse_args()
if not args.pdf.is_file():
print(f"error: file does not exist: {args.pdf}", file=sys.stderr)
return 2
if args.output:
try:
validate_output_path(args.output, [args.pdf])
except OutputPathError as exc:
print(f"error: {exc}", file=sys.stderr)
return 2
if args.deep and args.trust_level == "untrusted" and not args.sandbox_profile_confirmed:
print(
"error: deep parsing of an untrusted PDF requires --sandbox-profile-confirmed; "
"otherwise run the default raw-byte inspection only",
file=sys.stderr,
)
return 2
try:
raw = raw_inspection(args.pdf)
except OSError as exc:
print(f"error: unable to read {args.pdf}: {exc}", file=sys.stderr)
return 2
report: dict[str, Any] = {
"path": str(args.pdf.resolve()),
"bytes": args.pdf.stat().st_size,
"sha256": sha256(args.pdf),
"modified": False,
"trust_level": args.trust_level,
"sandbox_profile_confirmed": args.sandbox_profile_confirmed,
"inspection_mode": "deep" if args.deep else "raw-byte heuristic",
"raw": raw,
"available_capabilities": parser_inventory(),
"limitations": [
"Raw feature markers and page-object counts can be false positives or incomplete.",
"The inspector does not render pages, extract text, validate signatures, or prove redaction.",
"Active content is reported but never activated.",
"Sandbox confirmation is an operator assertion; this script cannot verify host isolation or parser configuration.",
],
}
if args.deep:
parser_result, parser_error = deep_with_pypdf(args.pdf)
pdfinfo_result, pdfinfo_error = deep_with_pdfinfo(args.pdf)
report["deep"] = {
"python_parser": parser_result,
"python_parser_error": parser_error,
"pdfinfo": pdfinfo_result,
"pdfinfo_error": pdfinfo_error,
}
payload = json.dumps(report, indent=2 if args.pretty else None, sort_keys=True) + "\n"
if args.output:
try:
validate_output_path(args.output, [args.pdf])
atomic_write_text(args.output, payload, [args.pdf])
except OutputPathError as exc:
print(f"error: {exc}", file=sys.stderr)
return 2
else:
sys.stdout.write(payload)
return 0
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |