What is filling-pdf-forms?

The Filling PDF Forms skill automates the completion of complex documents by transforming static or fillable PDFs into interactive, conversational interviews. It intelligently extracts form fields, manages data modeling, and supports real-time translation, allowing users to generate professionally populated PDF files through a simple chat interface.

When should I use filling-pdf-forms?

filling-pdf-forms is useful in the following scenarios: • Streamlining Onboarding: Convert lengthy HR, insurance, or membership registration PDFs into a guided chat to collect user data efficiently. • Multilingual Document Support: Assist users in completing forms written in foreign languages by conducting the data-collection interview in their native language. • Legal and Compliance Filings: Ensure high accuracy in legal or regulatory documents by using a structured interview loop to verify information before populating the final PDF. • Processing Non-Fillable Forms: Automatically detect fields in scanned or static PDF documents and overlay text to produce a completed '.done.pdf' without manual editing tools.

name	filling-pdf-forms
description	Complete PDF forms by collecting data through conversational interviews and populating form fields. Use when filling forms, completing documents, or when the user mentions PDFs, forms, form completion, or document population.
allowed-tools	Read, Write, Edit, Glob, Bash, Task
version	1.0.0a2
license	Apache 2.0

Filling PDF Forms

Complete PDF forms by collecting required data through conversational interviews and populating form fields.

Use when completing PDF forms with user-provided data. Goal: produce `.done.pdf` populated with user information by following this process exactly.

Process Overview

@startuml SKILL
title Filling PDF Forms - High-Level Workflow
|User|
start
:User provides PDF form to complete;
|filling-pdf-forms skill|
:Step 0: Initialize Chatfield;
:Step 1: Form Extraction;
:Step 2: Build Form Data Model;
:Step 3: Translation Decision;
if (User language is form language?) then (yes)
  :Use base Form Data Model;
else (no)
  :Translation Setup;
endif
:Step 4: Run Interview Loop;
partition "Chatfield CLI Interview Loop" {
  :Initialize: Run CLI without message;
  repeat
    :CLI outputs question to stdout;
    :Present question to user via AskUserQuestion();
    |User|
    :User provides response;
    |filling-pdf-forms skill|
    :Run CLI with user's message;
  repeat while (CLI indicates complete?) is (no)
  ->yes;
}
:Inspect collected data via CLI --inspect;
:Step 5: Populate PDF;
if (Fillable form?) then (yes)
  :Populate fillable fields
  (see Populating-Fillable.md);
else (no)
  :Populate non-fillable fields
  (see Populating-Nonfillable.md);
endif
|User|
:**✓ SUCCESS**;
:Receive completed PDF <basename>.done.pdf;
stop
@enduml

Workflow

Step 0: Initialize Chatfield

Test: python -c "import pypdf; import pdf2image; import markitdown; import chatfield".

Install via pip if needed; exceptions:

markitdown → pip install "markitdown[pdf]"
chatfield → pip install ./scripts/chatfield-1.0.0a2-py3-none-any.whl (relative to this .md)

Step 1: Form Extraction

Extract PDF form using extracting-form-fields sub-agent:

Task(
    subagent_type="general-purpose",
    description="Extract PDF form fields",
    prompt=f"Extract form field data from PDF: {pdf_path}\n\nUse the extracting-form-fields skill."
)

Task reports: "fillable" or "non-fillable" (needed for Step 5)

Creates (for input.pdf):

input.chatfield/input.form.md - PDF as Markdown
input.chatfield/input.form.json - Field definitions
input.chatfield/interview.py - Template Form Data Model

Step 2: Build Form Data Model

Read entirely: ./references/Data-Model-API.md - Learn Chatfield API
Read entirely: ./references/Converting-PDF-To-Chatfield.md - PDF→Chatfield Form Data Model guidance
Edit <basename>.chatfield/interview.py - Define Form Data Model

Result: The Form Data Model, a faithful representation of PDF form using Chatfield API.

Step 3: Translation

Determine if translation is needed. Translation is needed either:

Explicit: User states "I need to fill this Spanish form but I only speak English"
Implicit: User request is in language X, but PDF is in language Y

Example: "Help me complete form.es.pdf" (English request, Spanish form)

State to the user whether you will translate. Either:

Claude: This form uses
or Claude: This form uses so I will set up translation to

To apply translation, see: ./references/Translating.md

Translation creates interview_<lang>.py and re-defines the Form Data Model from interview.py to the new interview_<lang>.py instead. Henceforth, use the translated file as the Form Data Model.

Step 4: Run Interview Loop via CLI

CRITICAL: See ./references/CLI-Interview-Loop.md for complete MANDATORY execution rules.

Step 5: Populate PDF

Parse --inspect output and populate the PDF.

If Fillable:

See: ./references/Populating-Fillable.md

If Non-fillable:

See: ./references/Populating-Nonfillable.md

Result: <basename>.done.pdf

filling-pdf-forms

When & Why to Use This Skill

Use Cases