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

examples/example-run.md

View on GitHub
# Worked example — mail-merge a confirmation letter over a list

A fictional, illustrative run. No binary templates are shipped — bring your own master `.docx`/`.xlsx`
and a data table. This shows the tokenise → confirm → generate flow end to end.

## The inputs (you supply these)

- **Master:** `Letter_master.docx` — a one-page letter that reads, in part:
  > Dear Ms Jordan Lee,
  > We confirm your subscription of **$1,000,000**, effective **01 Jul 2026**. Your reference is
  > **REF-0001**.
- **Data:** `recipients.csv` with a header row:

  ```csv
  Recipient,Amount,EffectiveDate,Reference
  Ms Jordan Lee,1000000,2026-07-01,REF-0001
  Mr Sam Okafor,2500000,2026-07-01,REF-0002
  Dr Mei Chen,500000,2026-07-08,REF-0003
  ```

## 1–2. Analyse, then propose tokens

```python
from fill_template import read_content, tokenise, tokens_in, load_rows, generate

print(read_content("Letter_master.docx"))   # eyeball the varying parts
```

Proposed tokens (note `Recipient` differs from the name in the letter, so it's mapped later):
`Ms Jordan Lee → {{Name}}`, `$1,000,000 → {{Amount}}`, `01 Jul 2026 → {{EffectiveDate}}`,
`REF-0001 → {{Reference}}`.

## 3. Confirm, then tokenise

After the user signs off the token list:

```python
rep = tokenise("Letter_master.docx", "Letter_tokenised.docx",
               [{"find": "Ms Jordan Lee", "token": "Name"},
                {"find": "$1,000,000",    "token": "Amount"},
                {"find": "01 Jul 2026",   "token": "EffectiveDate"},
                {"find": "REF-0001",      "token": "Reference"}])
print(rep["not_found"])         # must be empty before generating
print(tokens_in("Letter_tokenised.docx"))   # {'Name','Amount','EffectiveDate','Reference'}
```

## 4–5. Load data and generate one file per row

```python
headers, rows = load_rows("recipients.csv")

report = generate(
    "Letter_tokenised.docx", rows,
    token_to_column={"Name": "Recipient"},     # token Name ← column Recipient; the rest match
    outdir="out",
    name_pattern="Letter_{Recipient}",
)
```

`1000000` renders as supplied (format the column in the data file if you want `$1,000,000`);
`2026-07-01` renders as **01 Jul 2026**.

## 6. Report back

```
3 files written to out/:
  out/Letter_Ms Jordan Lee.docx
  out/Letter_Mr Sam Okafor.docx
  out/Letter_Dr Mei Chen.docx
unmapped_tokens: []      missing (per file): none
```

If any token had no value for a row, that file would contain a visible `«MISSING: Token»` flag and the
report would list it — fix the data or the mapping and re-run rather than hand-editing the output.
These are **drafts for a person to review** before they go out.
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 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 CodeCodexVerifiedInstall