Skip to content

moonlight-lupin/agent-skills / productivity/fill-template

fill-template

Verified

Use when the user wants to "fill in this letter for each person", "mail merge", "generate letters for this list", "turn this filled letter into a template", or hands over a template plus a list. Bulk-fills ONE master template — a Word (.docx) letter/form or an Excel (.xlsx) form — from a data table, one filled file per row (mail-merge); or the reverse: extract a reusable tokenised .docx template + data-table skeleton from a filled example document, confirm the mapping, then fill. Reads the master, proposes a TOKENISED version (varying parts become {{tokens}}), confirms the mapping, then regenerates one output per data row, preserving the master's layout exactly. Data is an .xlsx or .csv (one row per output); outputs are one named file per record. Never invents: a token with no data is a VISIBLE flag, never a silent blank. Runs fully local and generates files only — it does not send, post or sign. Extract is .docx only this round (not .xlsx). Not a substitute for a hand-crafted single letter.

FileKindSize
README.mdmarkdown1.2 KB
SKILL.mdskill md11.3 KB
examples/example-run.mdmarkdown2.6 KB
references/tokenising-guide.mdmarkdown4.5 KB
requirements.txtmanifest129 B
scripts/fill_template.pyscript46.4 KB
tests/__init__.pyscript0 B
tests/test_fill_template.pyscript61.7 KB

references/tokenising-guide.md

View on GitHub
# Tokenising guide — choosing and naming tokens well

The quality of a batch run is set at the **tokenise** step. Get the template right once, confirm it,
then fan it out. This guide is the curated knowledge for that step.

## What to tokenise (the parts that vary row to row)

Tokenise anything that changes from one output to the next:

- **Recipient identity** — name, salutation ("Dear Ms Lee,"), title, organisation, address lines.
- **Amounts** — price, fee, balance, quantity. (Format the *number* in the data file; the token just
  drops it in.)
- **Dates** — effective date, period, deadline. Dates from the data render **DD MMM YYYY**.
- **References** — account/order/reference numbers, project names.
- **Any other field that differs** — an account, a percentage, a location.

## What NOT to tokenise (the boilerplate that stays fixed)

Leave the standing text alone — the body prose, the organisation's name, the sign-off block, fixed
headings, header/logo, footer. If it's the same in every output, it's not a token.

> One subtle case: a phrase like the salutation often **repeats** (recipient line *and* "Dear …,").
> That's fine — `tokenise` replaces *every* occurrence of the matched phrase, so one `{{Name}}` token
> covers both. The hit count in the report tells you how many places it landed.

## Naming tokens

- **Match the data file's column headers** wherever you can — the token→column mapping then defaults
  automatically (case-insensitive). If the column is `Name`, call the token `{{Name}}` and skip a
  mapping entry.
- Use clear, specific names: `{{Amount}}`, `{{EffectiveDate}}`, `{{Reference}}` — not `{{Field1}}`.
- No spaces are needed inside the braces, but they're tolerated: `{{ Name }}` works.

## The `find` text must be exact

`tokenise` locates each phrase by an **exact** substring match against the master's text.

- Copy the phrase exactly as it appears — including punctuation and currency symbols (`$1,000,000`,
  not `$ 1,000,000`).
- After tokenising, check the report's `not_found` list. Anything there means the `find` text didn't
  match — fix the phrase and re-run *before* generating the batch.
- The `hits` count is a sanity check: if you expected a token in three places and it shows one, the
  other two are worded differently and need their own `find` entries.

## Letters (.docx) vs forms (.xlsx)

- **Letters / .docx forms** — tokens sit inside sentences and table cells. Replacement is run-aware,
  so a token inside a **bold** or coloured span keeps that formatting.
- **.xlsx forms** — put a token in the cell where the value belongs (e.g. `B5` = `{{Name}}`).
  Formulas, totals and formatting elsewhere are preserved. The data table is a *different* file from
  the form template — don't confuse the two.

## The confirm step (do not skip)

Before generating, present the proposed token list back to the user as plain language and **wait for
explicit sign-off**:

> Proposed tokens: `Ms Jordan Lee → {{Name}}`, `$1,000,000 → {{Amount}}`, `01 Jul 2026 →
> {{EffectiveDate}}`, `REF-0001 → {{Reference}}`. Shall I generate?

This is the cheapest place to catch a mistake — fixing the template once beats re-issuing a whole
batch.

## Never invent — the MISSING flag

If a token has no value for a row (no mapped column, or the cell is blank), the output shows
`«MISSING: Token»` in place — a visible, greppable flag, never a silent blank or a guessed value.
These are listed per file in the `generate` report. Resolve them by fixing the data or the mapping
and re-running; do not hand-edit an invented value into the output.

## Extracting a template from a filled example

`extract_template` is the reverse of tokenise: it finds values that **differ across repeating
instances** and replaces them with `{{Token}}`, leaving boilerplate literal.

- Token names come from five typed shapes only: after `Dear ` → `Recipient`; `$…` → `Amount`;
  `INV-123` → `InvoiceRef`; dates like `12 Mar 2026` → `Date`; `ACME-0042` → `AccountRef`.
  Collisions become `Amount2`, …. A generic `Value1`/`Value2` fallback is **not implemented**;
  untyped variation is left literal. Fall back to manual `tokenise` for those fields.
- Values identical in every instance stay boilerplate.
- A document with no repeats is one instance: the five typed shapes are still tokenised;
  untyped variation is left literal (never-invent). Show `uncertain` with the mapping before reuse.
- The source file is never written. Outputs are `<name>_tokenised.docx` and `<name>_data.csv`.
deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexUnverifiedInstall
agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json.Stars: 118kUpdated Claude CodeCodexUnverifiedInstall