jhs avatar

filling-pdf-forms

Complete PDF forms through conversation

GitHub stars
6

Install

/plugin install filling-pdf-forms@Chatfield

Run it inside Claude Code after adding the marketplace with /plugin marketplace add jhs/Chatfield.

Contents

Discovered from source

Skills 2

Extracting Form Fields

Prepare working directory and extract field data from PDF forms.

This skill extracts PDF form information into useful JSON. - Detects fillable vs. non-fillable PDFs - Extracts PDF content as readable Markdown - Creates field metadata in common JSON format

Inputs

  • PDF path: Path to PDF file (e.g., /home/user/input.pdf)

Process Overview

@startuml SKILL
title Extracting Form Fields - High-Level Workflow
start
:Create working directory;
:Copy interview template;
:Extract PDF content as Markdown;
:Check Fillability;
if (PDF has fillable fields?) then (yes)
  :Fillable workflow
  (see Fillable-Forms.md);
else (no)
  :Non-fillable workflow
  (see Nonfillable-Forms.md);
endif
:**✓ EXTRACTION COMPLETE**;
:Ready for Form Data Model creation;
stop
@enduml

Process

1. Create Working Directory

mkdir <basename>.chatfield

2. Copy Interview Template

Copy a file from the included filling-pdf-forms skill's template. The example path below is relative to this skill directory.

cp ../filling-pdf-forms/scripts/chatfield_interview_template.py <basename>.chatfield/interview.py

3. Extract PDF Content

markitdown <pdf_path> > <basename>.chatfield/<basename>.form.md

4. Check Fillability

python scripts/check_fillable_fields.py <pdf_path>

Output:

  • "This PDF has fillable form fields" → use fillable workflow
  • "This PDF does not have fillable form fields" → use non-fillable workflow

5. Branch Based on Fillability

If Fillable:

Follow ./references/Fillable-Forms.md

If Non-fillable:

Follow ./references/Nonfillable-Forms.md

Output Format

Fillable PDFs - .form.json

[
  {
    "field_id": "topmostSubform[0].Page1[0].f1_01[0]",
    "type": "text",
    "page": 1,
    "rect": [100, 200, 300, 220],
    "tooltip": "Enter your full legal name",
    "max_length": null
  },
  {
    "field_id": "checkbox_over_18",
    "type": "checkbox",
    "page": 1,
    "rect": [150, 250, 165, 265],
    "checked_value": "/1",
    "unchecked_value": "/Off"
  }
]

References

  • ./references/Fillable-Forms.md - Fillable PDF extraction workflow
  • ./references/Nonfillable-Forms.md - Non-fillable PDF extraction workflow

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

  1. Read entirely: ./references/Data-Model-API.md - Learn Chatfield API
  2. Read entirely: ./references/Converting-PDF-To-Chatfield.md - PDF→Chatfield Form Data Model guidance
  3. 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

Commands 1

Form Command

Use the filling-pdf-forms skill to help the user complete their indicated PDF form.

Agents 1

Extract Form Fields from PDF

You are a specialized PDF form field extraction agent with expertise in analyzing both fillable and non-fillable PDFs.

Your Output: Structured field metadata files ready for chatfield interview creation

Input

You will receive: - **PDF path**: Filesystem path to the PDF file (e.g., `/home/user/documents/application.pdf`)

Task Overview

<task_summary> Use the extracting-form-fields skill to extract form field data from the PDF.

The skill will automatically:

  1. Determine if the PDF is fillable or non-fillable
  2. Create working directory (<basename>.chatfield/)
  3. Extract PDF content as Markdown
  4. Extract field metadata (automatically for fillable PDFs, guided for non-fillable PDFs)
  5. Copy the interview template </task_summary>

If an unrecoverable error happens, halt and report the error verbatim.

Process

Before beginning extraction, think through: 1. What is the PDF file path provided by the user? 2. Is this path absolute or relative? (Convert to absolute if needed) 3. What is the basename for this PDF? (e.g., `tax-form.pdf` → `tax-form`)

Output

When complete, state whether the PDF file is "FILLABLE" or "NON-FILLABLE"

Sponsors

Details

Marketplace
jhs/Chatfield
Source
Claude/filling-pdf-forms
Category
Community