How to Install the Template Builder Skill and Convert a PDF Into a Template

Our template editor has an AI Assistant in it. Describe the document you want, or upload a file for it to work from, and it builds the template. If that covers what you need, use it, it is the shortest route there is.

This article is about doing the same job somewhere else: on your own machine, with the AI subscription you already pay for, spending none of your PDF Generator API credits.

For that we publish an open source Agent Skill. It teaches your AI agent our template format, measures your source document with scripts rather than reasoning about its geometry, and validates the result before handing it to you. Two useful things follow from where it runs. It can see your filesystem, so one session can work through a whole folder instead of one file at a time. And it gives you files rather than writing into your workspace, so a template arrives as JSON you can review, diff and commit like anything else in your repository.

Before you start

You need three things.

Claude Code, or a Claude app. The Skill is in Anthropic's open Agent Skills format. Claude Code is the one worth using here, because only an agent with filesystem access can walk a folder of documents. The web and desktop apps work for one document at a time.

Python 3. The Skill runs real scripts rather than reasoning about geometry. Python 3 ships with macOS and most Linux systems already.

Two Python packages, both optional but both worth having: jsonschema for the schema check and pymupdf for reading PDFs. A missing package degrades to a warning rather than a crash, but you lose the step it powers.

pip install "jsonschema>=4" pymupdf

You do not need an API key, and you do not need to be online. The default workflow runs entirely against the schema bundled inside the Skill.

Step 1: Install the Skill

Clone the repository and copy the skill's source directory into your skills folder, named after the skill.

git clone https://github.com/pdfgeneratorapi/skills.git
mkdir -p ~/.claude/skills
cp -r skills/pdfgeneratorapi-template-builder/source ~/.claude/skills/pdfgeneratorapi-template-builder

Only the source directory becomes the installed Skill. The README and the packaged bundle sit outside it and are not copied.

If you want your whole team to have it, use a repository's own .claude/skills/ directory instead of ~/.claude/skills/. Commit it, and everyone who clones the repository gets the Skill with it.

Using a Claude app instead? Download pdfgeneratorapi-template-builder.skill from the repository and upload it under Settings, then Capabilities, then Skills. The bundle is a plain zip, so rename it to .zip if the uploader refuses the extension.

Step 2: Start a new session

The Skill is picked up when a session starts, so start a fresh one after installing. There is no command to run and nothing to switch on. The Skill activates by itself when what you ask matches what it does.

Step 3: Put your documents where the agent can see them

Create a folder and drop the documents in. Anything the agent can read on your filesystem works, so the location is up to you.

mkdir -p ~/Desktop/legacy-docs

A note on what converts well. PDFs are measured directly and give the best fidelity. Word files are converted with LibreOffice first, so you need LibreOffice installed for a .docx source. Images work, but a screenshot or a photo has no extractable coordinates, so positions are proportional estimates rather than measurements. The Skill says so in its summary rather than pretending otherwise.

Step 4: Ask for the conversion

Ask in your own words. The Skill picks its path from how you phrase it: describe a document and it designs one, point at a file and it replicates it.

For one document:

Convert ~/Desktop/legacy-docs/invoice.pdf into a PDF Generator API template.
Keep the layout as close to the original as you can, and turn names, dates,
amounts and line items into data fields.

For the whole folder:

Convert every PDF in ~/Desktop/legacy-docs into a PDF Generator API template.
Keep each layout as close to the original as you can, turn names, dates,
amounts and line items into data fields, and validate each pair before you
move to the next document.

Batching is worth understanding properly, because it is not a mode you switch on. The Skill's contract is one document in, one template plus dataset out. What makes a folder work is where the Skill runs: an agent in your terminal can see your filesystem, so it applies that contract to each file in turn and validates every pair before moving to the next one.

Step 5: Let it work

You will see the agent run scripts rather than reason its way through the layout. That is the point of the Skill, so it is worth knowing what each step is doing.

1. It measures your source. measure_pdf.py pulls text spans, rectangles, lines and images out of the PDF with geometry in centimetres, along with colours and fonts.
2. It reads the component reference and the official schema. Both are bundled. This is the part a model working without the Skill gets wrong, because it writes plausible JSON borrowed from some other template system.
3. It writes the template and a matching dataset.
4. It hydrates. hydrate_template.py fills in the editor property defaults. A template can be schema valid and still fail to import if it is too sparse, and this is the step that prevents that. It only adds keys, it never overwrites yours.
5. It validates. validate_template.py runs the schema check, a layout lint and a cross check of every placeholder against the dataset. Bounds, overlaps, table columns that do not sum to the table width, placeholders that do not resolve.

The agent is not allowed to hand you a template that fails validation. If something does not pass, it fixes it and runs the check again.

Step 6: Read what came back

Each document produces two files.

You also get a plain summary of the fields your application has to send.

Do not skip the second file. It is the contract between your integration and your template: it tells your developer exactly what JSON to produce, and it is the thing to hand over when someone asks what the API call should look like.

Step 7: Review before you import

The Skill hands you files rather than writing into your workspace, and that is deliberate. Templates are JSON, so review them the way you review anything else: open the pair side by side, diff them, commit them to your repository, open a pull request.

If you converted a folder, this is where the validator earns its place. It has already told you which pairs are clean, so your review is a check on layout judgement rather than a hunt for broken JSON.

Step 8: Import into your workspace

In your PDF Generator API workspace, open the template list and use Import, then pick the *-template.json file.

Open the imported template in the editor and preview it. The output follows editor conventions, with hydrated properties, dataIndex and {value} binding and static header rows, so it stays editable by hand from here. Anything you want to change, change it in the editor as usual.

If you have our MCP connector configured and you explicitly ask for it, the Skill can create the template in your account directly instead of handing you a file. It will not touch the connector unless you ask.

Validating or fixing a template you already have

There is a third way to use the Skill that is easy to miss. Paste in or attach a template definition you already have and ask for it to be validated or fixed.

Validate this template definition and fix the layout errors.

Same schema check, same lint, run against your JSON. This is useful on templates that import but render wrong, because the lint catches the layout problems that a schema check alone will pass.

Using the scripts without an agent

The four scripts are ordinary command line tools and they work on their own.

validate_template.py is the one to steal. Put it in your pipeline in front of every template import and you catch bounds errors, overlaps, broken column sums and unresolved placeholders before our API ever sees them. It exits 0 when there are no errors, so it drops straight into CI.

Get the Skill

The repository is public and MIT licensed at github.com/pdfgeneratorapi/skills. Issues and pull requests are welcome, and corrections to the component reference are the most useful thing you can send. If you convert something and it comes out wrong, the template it got wrong is the best possible bug report.

Updated on: 27/08/2026