moonlight-lupin/agent-skills / productivity/fill-template
fill-template
VerifiedUse 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.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 1.2 KB |
| SKILL.md | skill md | 11.3 KB |
| examples/example-run.md | markdown | 2.6 KB |
| references/tokenising-guide.md | markdown | 4.5 KB |
| requirements.txt | manifest | 129 B |
| scripts/fill_template.py | script | 46.4 KB |
| tests/__init__.py | script | 0 B |
| tests/test_fill_template.py | script | 61.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`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |