Processing PDF Documents Using Claude Skills: Complete Toolkit Guide

The ComposioHQ/awesome-claude-skills repository provides a self-contained Python toolkit for extracting, validating, and filling PDF form fields through CLI scripts that Claude can orchestrate directly.

The awesome-claude-skills repository delivers a production-ready solution for processing PDF documents using Claude skills. Located under document-skills/pdf/scripts, this toolkit enables Claude agents to handle fillable forms, validate inputs, and generate visual previews without external API dependencies. By leveraging pure-Python libraries like pypdf and pdf2image, these scripts create a seamless bridge between Claude's reasoning capabilities and low-level PDF manipulation.

PDF Processing Architecture

The toolkit follows a four-stage pipeline designed for Claude-agent automation: extraction, validation, filling, and rendering. Each stage is implemented as an independent CLI script, allowing Claude to chain them together or invoke them individually based on task requirements.

Field Extraction Pipeline

The extract_form_field_info.py script serves as the discovery layer. It loads PDF documents using pypdf, walks through annotations to identify fillable fields, and normalizes field types (text, checkbox, choice, radio) into a hierarchical JSON structure.

According to the source code in document-skills/pdf/scripts/extract_form_field_info.py【/cache/repos/github.com/ComposioHQ/awesome-claude-skills/master/document-skills/pdf/scripts/extract_form_field_info.py#L11-L38】, the extraction logic:

• Reads the PDF document structure
• Discovers form field annotations across all pages
• Builds hierarchical field IDs that preserve the document's logical organization
• Outputs a machine-readable JSON schema that Claude consumes to determine what data to supply

Validation Layer

Before writing data back to a PDF, the fill_fillable_fields.py script enforces type safety through validation_error_for_field_value. This function, located at lines 59-75【/cache/repos/github.com/ComposioHQ/awesome-claude-skills/master/document-skills/pdf/scripts/fill_fillable_fields.py#L59-L75】, checks:

• Checkbox values against allowed states
• Radio-group selections against available options
• Choice field inputs against permitted values

This validation ensures that Claude-generated data respects the PDF's internal constraints before the document is modified.

Form Filling Engine

The filling operation uses pypdf's PdfWriter to update form fields while preserving appearance streams. The implementation in fill_fillable_fields.py【/cache/repos/github.com/ComposioHQ/awesome-claude-skills/master/document-skills/pdf/scripts/fill_fillable_fields.py#L47-L55】 creates a new PDF writer instance, updates each page's form fields with validated values, and calls set_need_appearances_writer(True) to force PDF viewers to regenerate visual representations of the filled data.

PDF-to-Image Conversion

For OCR workflows or visual verification, convert_pdf_to_images.py transforms each PDF page into a PNG using pdf2image's convert_from_path. The script scales images to a configurable maximum dimension (default 1000 pixels) to optimize storage and transmission, as implemented at lines 10-22【/cache/repos/github.com/ComposioHQ/awesome-claude-skills/master/document-skills/pdf/scripts/convert_pdf_to_images.py#L10-L22】.

Working with the PDF Toolkit

These scripts operate as pure-Python CLIs, making them ideal for Claude skill definitions. Below are executable patterns for common workflows.

Extracting Field Definitions

Claude first needs to understand the PDF structure before filling it. Use this pattern to generate the field schema:

import subprocess, json, pathlib

pdf_path = pathlib.Path("sample_form.pdf")
json_path = pathlib.Path("fields.json")

# Run the extractor script

subprocess.run([
    "python",
    "document-skills/pdf/scripts/extract_form_field_info.py",
    str(pdf_path),
    str(json_path)
], check=True)

# Load the generated JSON for Claude analysis

with open(json_path) as f:
    fields = json.load(f)
print(json.dumps(fields, indent=2))

The extractor writes a JSON file describing every fillable field, including page numbers, field types, and allowed values【/cache/repos/github.com/ComposioHQ/awesome-claude-skills/master/document-skills/pdf/scripts/extract_form_field_info.py#L40-L45】.

Filling Forms with Validated Data

Once Claude generates values, validate and write them back to the PDF:

import json, subprocess, pathlib

input_pdf = pathlib.Path("sample_form.pdf")
output_pdf = pathlib.Path("filled_form.pdf")

# Example payload that Claude might produce

payload = [
    {"field_id": "name", "page": 1, "value": "Alice"},
    {"field_id": "agree_terms", "page": 1, "value": "/Yes"}  # checkbox value

]
payload_path = pathlib.Path("values.json")
payload_path.write_text(json.dumps(payload, indent=2))

# Run the filler script with validation

subprocess.run([
    "python",
    "document-skills/pdf/scripts/fill_fillable_fields.py",
    str(input_pdf),
    str(payload_path),
    str(output_pdf)
], check=True)

print(f"Filled PDF saved to {output_pdf}")

The filler validates values through validation_error_for_field_value before committing changes via PdfWriter【/cache/repos/github.com/ComposioHQ/awesome-claude-skills/master/document-skills/pdf/scripts/fill_fillable_fields.py#L12-L55】.

Converting PDFs to Images

Generate visual previews for Claude to analyze or for downstream OCR processing:

import subprocess, pathlib

pdf_path = pathlib.Path("sample_form.pdf")
out_dir = pathlib.Path("pages")
out_dir.mkdir(exist_ok=True)

subprocess.run([
    "python",
    "document-skills/pdf/scripts/convert_pdf_to_images.py",
    str(pdf_path),
    str(out_dir)
], check=True)

print(f"Images written to {out_dir}")

This renders each page as a PNG while maintaining aspect ratio within the configured max_dim limit【/cache/repos/github.com/ComposioHQ/awesome-claude-skills/master/document-skills/pdf/scripts/convert_pdf_to_images.py#L10-L24】.

Handling Edge Cases and Compatibility

The toolkit includes a compatibility shim for a known pypdf bug affecting selection-list fields. The fill_fillable_fields.py script contains a monkey-patch that replaces DictionaryObject.get_inherited to return a flat list of option values for the /Opt key, located at lines 88-104【/cache/repos/github.com/ComposioHQ/awesome-claude-skills/master/document-skills/pdf/scripts/fill_fillable_fields.py#L88-L104】.

This patch activates automatically when the filler script runs, ensuring reliable handling of dropdown and listbox fields without requiring manual intervention.

Summary

• Field extraction uses extract_form_field_info.py to parse PDF annotations and emit JSON schemas describing fillable fields, their types, and constraints.
• Validation occurs in fill_fillable_fields.py through validation_error_for_field_value, which verifies checkbox, radio, and choice values against allowed options before writing.
• Form filling preserves document integrity by using PdfWriter with set_need_appearances_writer(True) to ensure filled values display correctly in standard viewers.
• Image conversion leverages pdf2image to create scaled PNGs of each page, enabling visual verification and OCR workflows.
• Compatibility is maintained through automatic monkey-patching of pypdf's /Opt handling for selection lists.

Frequently Asked Questions

What output format does the field extraction script produce?

The extract_form_field_info.py script generates a JSON file containing an array of field objects. Each object includes the field_id, page number, field_type (text, checkbox, choice, or radio), and allowed values for constrained fields. Claude reads this schema to determine what data it can legally insert into the form.

How does the toolkit validate data before filling PDF forms?

Validation occurs in fill_fillable_fields.py through the validation_error_for_field_value function, which checks whether supplied values match the field's expected type and allowed options. For checkboxes, it verifies against /Yes and /Off states; for choice fields, it validates against the /Opt list. This prevents Claude from inserting invalid data that would corrupt the PDF.

Can these scripts handle complex PDF forms with radio buttons and dropdowns?

Yes. The toolkit specifically handles radio groups, checkboxes, and selection lists (dropdowns). The extraction script identifies these field types from PDF annotations, while the filler script manages their unique value requirements. A compatibility patch in fill_fillable_fields.py addresses a known pypdf quirk with /Opt keys to ensure dropdown fields populate correctly.

How do I convert PDF pages to images for Claude to analyze visually?

Use convert_pdf_to_images.py to render each page as a PNG. The script uses poppler (via pdf2image) to convert the PDF at 200 DPI, then scales images to stay under a configurable maximum dimension (default 1000 pixels). This produces lightweight images suitable for Claude's vision capabilities or external OCR services while preserving text readability.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}