agentleFS
Plexito-dePlexito-de/honed-skills/skills/comb-pdf-form-filling/SKILL.md

comb-pdf-form-filling

Skill3 starsChanged 22 days agoApache-2.0View on GitHub

Use when filling an official PDF form to print, sign or submit, and each character has to land inside its own printed box (a comb field) - IBAN, tax number, BIC, postcode, dates. Covers German Behörden-, Steuer- and Bank-Vordrucke (SEPA-Lastschriftmandat, Finanzamt and insurer forms) and any AcroForm or flat PDF with printed boxes. Triggers on comb field, Kästchen, one letter per box, Vordruck, Formular ausfüllen, fillable PDF, AcroForm, flatten PDF, and on filled text that crosses the box dividers or will not fit.

  • Installs packages

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When a previously "filled" form shows text straddling the cell dividers, or a value is too long for the boxes.

    line 35
  2. Very specific:

    Plain line (no boxes), OR value longer than the cells: write continuously, left-aligned at x0+2.

    line 66
  3. Distinctive:

    If you attach it to a message, attach it by file path.

    line 106
  4. Distinctive:

    Keep filled forms out of version control.

    line 107

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Comb-box PDF form filling

What a comb field is

A comb field prints one open box per character, so the form expects one glyph per box. Filling it as an ordinary text field puts a continuous string over the top and the characters land across the dividers, which is what an authority rejects:

Image: A comb field filled wrongly as one continuous string, and filled correctly with one glyph centred per box

Both rows above hold the same value in the same field. The top one is what you get by default; the bottom one is what this skill produces. Regenerate the image with the illustration script under scripts/, and note that the image lives at docs/assets/ in the repository rather than inside this folder: a skill folder that bundles a binary is reported HIGH by a security scanner that cannot read it, at a fixed confidence, twice over. Keeping the folder text-only costs nothing and the image still renders here.

Overview

Fill an official form so it looks typed by a clerk: every character sits inside its printed box, identifying numbers (IBAN, tax number, BIC) are unambiguous, and the result prints the same everywhere. Two principles carry the whole skill:

  1. Place glyphs by geometry, then VERIFY BY RENDERING. A filled AcroForm can look right in one viewer and wrong in another, and a value written to the wrong state looks like a successful write. The only proof is to rasterize the finished PDF and read the pixels. Do it every time, on every page, and check the identifying numbers box by box.
  2. The AcroForm "comb" flag does NOT mean the form draws visible boxes. Decide per-cell vs. continuous from the boxes actually drawn on the page (render the blank and look), never from the field flag. Seen in practice: a bank-name field carried comb=YES with MaxLen 21 and had no dividers printed at all, so per-cell spacing there looked absurd.

Vocabulary, because the forms this was built against are German: Vordruck is an official blank form, Behörde a public authority, Kästchen the printed box, Steuernummer a German tax number (13 characters, written with slashes, e.g. 12/345/67890), SEPA-Lastschriftmandat a direct-debit authorisation.

When to use

  • Filling a government, tax, bank or insurance PDF that will be printed, signed, and posted or uploaded.
  • Any fillable-PDF task where characters must land in individual boxes, especially account, tax or ID numbers.
  • When a previously "filled" form shows text straddling the cell dividers, or a value is too long for the boxes.

Not for: generating a document from scratch (author it in HTML/LaTeX), or forms the recipient fills online. For general PDF work (extraction, merge and split, OCR, ordinary AcroForm filling) prefer the Anthropic pdf skill; see Prior art.

Toolchain

JobToolNote
Read AcroForm fields (name, /Rect, /MaxLen, comb)pypdfresolve inherited keys up the whole parent chain
Detect drawn boxes on the blankrender + look (primary); pdfplumber edges (secondary)edge-counting is noisy, see gotchas
Draw each glyph at a coordinatereportlab canvas overlayone glyph per cell, centred
Merge overlay onto the pagepypdf page.merge_page()overlay becomes page content, so it survives flattening
Flatten to static, compressqpdf --warning-exit-0 --generate-appearances --flatten-annotations=all --object-streams=generate --compress-streams=y --recompress-flate --compression-level=9turns form values into ordinary page content. It removes interactivity; it does NOT make the file uneditable and is not an integrity guarantee
Render to verifypdftoppm -png -r 150 <out.pdf> <prefix>every page, not just page 1, then READ the PNGs. MANDATORY

Set the Python side up in a throwaway environment, so nothing lands in a project env:

python3 -m venv /tmp/combfill && /tmp/combfill/bin/pip install pypdf reportlab pdfplumber

The two binaries come from your package manager: brew install qpdf poppler on macOS, apt install qpdf poppler-utils on Debian or Ubuntu. On Windows use WSL, or fetch qpdf and poppler builds and put both on PATH.

The method

  1. Get the current official blank from the authority's own site. Note the form number and version printed on it, because they change and the coordinates change with them. Keep that file; it is the fill source.
  2. Inspect the form. For each widget print the fully qualified field name, /Rect [x0,y0,x1,y1] (PDF coords, origin bottom-left), /MaxLen, the comb flag, and for a checkbox its real checked state. Resolve /FT, /Ff, /MaxLen and /T by key presence up the full parent chain, never with or: an explicit local /Ff of 0 is falsy, so local or parent silently reports a plain field as a comb field. Note the exact spelling of each value you must enter, since an agency or bank often stores names in ASCII without diacritics. If there is no AcroForm at all (a flat scan), there are no /Rects: measure the boxes off a 150-dpi render (pixels to points) and go straight to step 4. Skip every form-field call, including update_page_form_field_values, which raises without an /AcroForm.
  3. Map which fields have VISIBLE boxes. Render the blank at 150 dpi and read it; crop uncertain rows. This map, not the comb flag, drives placement.
  4. Place text on an overlay canvas sized from the page's own mediabox, not assumed A4:
    • Box field, value fits (len ≤ cells): one glyph per cell, centred. cell_w = (x1-x0)/cells; for char i, center_x = x0 + (i+0.5)*cell_w, drawn at center_x - stringWidth(ch)/2, with baseline = y0 + ((y1-y0) - fontsize*0.70)/2. The 0.70 approximates cap height as a fraction of font size, so confirm the vertical position in the render rather than trusting it.
    • Plain line (no boxes), OR value longer than the cells: write continuously, left-aligned at x0+2; drop the font size for a long value. Long-value-in-boxes is the "where it fits" case: continuous is correct, do not shrink to cram.
    • Drawn boxes with NO AcroForm field (a tax-number comb, for instance): detect the cell boundaries from the page's vertical vector edges in that row and place per detected cell. n characters need n+1 boundaries; assert it.
    • Pre-fill alignment check (cheap iteration): before filling for real, render the blank with your computed cell centres drawn as ticks or thin rectangles and compare them against the printed boxes. A mis-measured /Rect is one pass to fix here, instead of a full fill, flatten and render cycle to discover. (The same idea appears as a validation-image step in the anthropics/skills pdf skill; the implementation here is independent and no code or text was copied.)
  5. Checkboxes: read each box's own checked state; never assume /On. Take the non-/Off key from the widget's /AP /N dictionary, because forms use /Yes, /1, /Ja and others. pypdf substitutes /Off when the name you ask for is not in that dictionary, so a guessed /On silently leaves the box UNTICKED while the call reports success. On a mandate the tick is the authorisation, so this is the difference between granting something and granting nothing. Verify the tick in the render.
  6. Leave signature and date boxes empty, since a wet signature is the point. Prefill a known place if asked.
  7. Flatten + compress with the qpdf line above, writing to a fresh temporary file and moving it into place only after success. --warning-exit-0 makes a warning exit 0 so check=True fires only on a real error. Without that discipline a fatal exit is swallowed, and because qpdf leaves an existing output file untouched when it errors, the next step renders the PREVIOUS run's PDF and the visual check certifies the wrong document.
  8. Verify by rendering EVERY page (pdftoppm -png -r 150), read the PNGs, and confirm each identifying number sits one-per-box. -f 1 -l 1 checks page 1 only while qpdf rewrote them all. Fix coordinates and re-render until right.
  9. Hand over the flattened PDF and say plainly what is left for the pen.

Gotchas

SymptomCause / fix
Text crosses the cell dividersYou filled the AcroForm field directly; its appearance is continuous. Draw glyphs per-cell as an overlay and leave the field empty.
A field is spaced into boxes that don't exist on paperTrusted the comb flag. Go by the drawn boxes in the render.
The glyphs are in the file (pdftotext finds them) but the render shows an empty shaded boxThe widget appearance has a background (/MK /BG) and paints over your page content. Flatten the blank widget appearances first, keeping their borders, then merge the text overlay.
A plain field is reported as comb, or two fields print with the same name/Ff resolved with or, so an explicit 0 fell through to the parent; and a bare /T is only the leaf name. Resolve inherited keys by presence up the full chain and build the qualified name.
A checkbox stays empty although the call succeededThe form's checked state is not /On; pypdf fell back to /Off. Read the non-/Off key from /AP /N.
Divider auto-detection reports absurd counts (80 "dividers" where there are none)pdfplumber decomposes each box into several edges and adjacent rows bleed into the band. Don't threshold on raw counts: render the blank and look, or match the count to cells-1 per field.
Font dictionary for /HeBo not found; defaulting to Helveticapypdf appearance-font fallback. Harmless.
Value doesn't fit the boxes (e.g. a two-holder account name longer than the printed cells)Write it continuously ("where it fits"); don't shrink to cram.
One viewer shows blank fields, another shows themStale appearance streams: set NeedAppearances, or flatten so the values become page content.
The form is XFA and filling it changes nothing visibleDynamic XFA keeps the real form in XML, and the PDF pages may be fallback content only. Flattening those pages does not render the XFA layout or data, so detect /XFA first and route it through an XFA-capable renderer when the XML is authoritative.
Umlauts or accents look wrong, or the agency can't match the nameUse the exact registered spelling, often ASCII (Nunez not Núñez, Strasse not Straße). Confirm with the account holder.

Example

scripts/fill_example.py is a working template: inherited-key resolution, per-cell and continuous placement, checkbox state detection, a flat-PDF branch, private temp handling, strict qpdf exit handling, and an all-page render. Run it with no output path to inspect a blank first:

/tmp/combfill/bin/python scripts/fill_example.py BLANK.pdf              # print field geometry
/tmp/combfill/bin/python scripts/fill_example.py BLANK.pdf OUT.pdf      # fill, then READ the PNGs
python3 scripts/fill_example.py --selftest                              # offline selftest (no network, no blank)

It is a template to copy and re-coordinate, not a generic filler: every coordinate in it was measured from one specific blank and will be wrong for yours. Start by running the inspect mode against your own form and replacing the numbers and the checkbox names with what it prints.

Delivery

  • The flattened PDF is the deliverable. State explicitly what is left for the pen: date, signatures, and where they go.
  • If you attach it to a message, attach it by file path. Never hand-transcribe a PDF as inline base64 into a tool call: a 100 KB file cannot be reproduced byte-perfect by hand, and a corrupted attachment on an official document is unacceptable.
  • Keep filled forms out of version control. A filled form carries personal data, and a bank mandate carries an account number.

Prior art (checked 2026-09)

Complements, does not replace, the pdf skill in anthropics/skills, which ships a skill body, a forms guide, a reference document, a scripts directory and its own licence file. That is the better tool for general PDF work and for ordinary form filling: it extracts per-field metadata including each checkbox's own checked_value and unchecked_value, handles radio groups and choice fields, covers multi-page rects, and has a non-fillable coordinate-overlay route with a validation image. Read its LICENSE.txt before reusing anything from it: those materials are all-rights-reserved and separately forbid derivative works, a stricter grant than this repo's Apache-2.0. Nothing here is derived from them; where the two skills agree, they agree because the PDF format forces the same answer.

The other public option, claude-office-skills/pdf-form-filler, is a guidance document rather than a method: it lists candidate libraries (pdf-lib, PyPDF2, iText, PDFBox) and its own Limitations section states that it "cannot execute actual form filling".

Status

Technique-and-reference skill, not a rule set, so there is nothing here to pressure-test. It was worked out and verified against a real government comb-box Vordruck, with the result checked in the raster rather than assumed, and the gotchas table is the residue of the attempts that failed. Retest it by applying it to a new form and reading the render.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.