# Processing PDF Documents Using Claude Skills: Complete Toolkit Guide

> Master processing PDF documents with Claude skills using this Python toolkit. Extract, validate, and fill PDF forms via CLI scripts. Empower your workflows today.

- Repository: [Composio/awesome-claude-skills](https://github.com/composiohq/awesome-claude-skills)
- Tags: how-to-guide
- Published: 2026-07-27

---

**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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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:

```python
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:

```python
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:

```python
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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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`](https://github.com/ComposioHQ/awesome-claude-skills/blob/main/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.