Acroform Writer

Fill an existing PDF's real AcroForm fields with supplied data, and

optionally lock the result read-only so it's ready to send or file without

further edits. The goal is to write into the document's actual form fields —

never to paste text over a rendered page image, which drifts out of

alignment the moment a layout differs even slightly from what you assumed.

Instructions

• Find the source PDF via knowledge search — do not ask the user to upload it.

The blank fillable form (e.g. a job application, intake sheet, or contract

template) lives in the connected SharePoint knowledge source, not as a user

upload. Let the user refer to it naturally — by form name, topic, or

purpose ("the job application form", "our standard NDA template") — and use

those cues to search knowledge for the best-matching PDF. If exactly one

document is a clear match, proceed with it; only ask a brief clarifying

question when the match is genuinely ambiguous (multiple similarly-named

forms, or no clear candidate).

• Pull the FULL document, not retrieved chunks. A knowledge search only

needs to return enough to *find* the right file — form fields and their

full structure can be split or omitted across retrieval chunks. Once the

right document is identified, fetch the complete PDF into the sandbox (the

SharePoint knowledge source handles this — let it pull the full file down)

before doing anything else. Never attempt to reconstruct or fill a form

from a partial/chunked view of it.

• Collect the values to fill. These come from the conversation, an

attached spreadsheet row, or a connector record — collect them into a flat

{field_name: value} JSON object. Do not guess field names at this stage;

that happens against the PDF's real fields in the next step.

• Always list fields first. Run:

   python scripts/fill_form.py list <downloaded_form.pdf>

This prints every real form field (name, type, current value, and — for

checkboxes/radios/dropdowns — the valid states or options). Use this output

to map the data you collected in step 3 onto the PDF's actual field names.

If this reports no fields found (exit code 1), stop — the PDF has no

real AcroForm (commonly a scanned or flattened document already). Tell the

user this form isn't fillable this way and don't attempt to fake it by

drawing text over the page.

• Match data to fields carefully.
• Checkboxes/radio buttons must be set to one of the exact states values

reported in step 4 (typically /Yes and /Off), not true/false.

• Dropdown/choice fields must use one of the reported options values

verbatim.

• If a value you were given doesn't obviously map to any listed field, do

not force it into the closest-sounding one — leave it out and flag it to

the user rather than guessing.

• Fill (and lock read-only, if the result should be final):

   python scripts/fill_form.py fill <downloaded_form.pdf> <data.json> <output.pdf> [--flatten]

Add --flatten whenever the output is meant to be a finished, submission-

ready document (the common case) so the fields are marked read-only and

most viewers treat it as no longer editable. This is a best-effort lock,

not true flattening — the AcroForm and field definitions still exist in

the file, and a viewer that ignores the read-only flag could still edit

them. Leave --flatten off if the user explicitly wants to keep the

fields freely editable for further changes later.

• Check the JSON result the script prints. It reports fields_filled and

any unmatched_fields — data keys that didn't correspond to a real field.

Always surface unmatched fields to the user by name; never fill silently

and claim full completion if something was dropped.

• Hand back the file with a short, honest recap: which form (and, if

relevant, where it was sourced from in knowledge), how many fields were

filled, whether it was flattened, and any fields left blank or unmatched.

Do not paste the filled values back into the chat as a table — the file is

the deliverable.

Guardrails

• Never ask the user to upload the blank form — find it via knowledge search

first. Only fall back to asking the user directly for the file if knowledge

search turns up nothing plausible at all.

• Never fill from a partially retrieved/chunked view of the form — always

work from the complete downloaded PDF (step 2).

• Never draw or overlay text on a page image to fake-fill a PDF that has no

real form fields — detect that case (step 4) and say so plainly instead.

• Never invent a value for a field the user didn't supply; leave it blank and

say so.

• Never force a supplied value into a checkbox/radio/dropdown field using

anything other than that field's own reported states/options.

• Don't silently drop unmatched data — always report it.
• --flatten is about locking the PDF read-only, not about changing any of

the entered values — never alter data during that step.

Tone

Precise and matter-of-fact. State plainly what was filled, what wasn't, and

why — this skill is often used for documents with real consequences

(applications, contracts), so avoid overstating completeness.