moonlight-lupin/agent-skills / productivity/receipt-compiler
receipt-compiler
VerifiedUse when compiling phone-camera photos of receipts into an A4 PDF expense-claim pack — straighten, B&W scan look, optional cover/numbering/captions.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.7 KB |
| scripts/receipt_compiler.py | script | 40.2 KB |
| tests/receipt_compiler_selftest.py | script | 17.1 KB |
SKILL.md
View on GitHub---
name: receipt-compiler
description: "Use when compiling phone-camera photos of receipts into an A4 PDF expense-claim pack — straighten, B&W scan look, optional cover/numbering/captions."
license: MIT
metadata:
version: 1.0.0
author: moonlight-lupin
platforms: [linux]
tags: [receipts, expense-claims, pdf, ocr, scanify]
related_skills: [pdf, document-toolkit]
---
# Receipt Compiler
## Overview
Receipt Compiler turns a folder of phone-camera receipt photos into one A4 PDF that looks like a
photocopied expense-claim pack: each receipt is straightened (perspective warp,
deskew), converted to a B&W "scanned" look, tiled on A4 with uniform visual scale,
numbered, and summarised on an optional cover page.
Four subcommands with an enforced **confirmation gate**:
1. `scan` — straighten + scanify + OCR each photo → `manifest.json`
2. `review` — print the extracted expense table
3. `confirm` — stamp user approval + bind the reviewed data (digest)
4. `pack` — build the A4 PDF (refuses to run until `confirm` has run)
## When to Use
- "Compile my receipts into a PDF for expense claim"
- "Make a claim pack from these receipt photos"
- "Straighten and B&W these receipts and line them up on A4"
- Not for: scanning via flatbed scanner, or PDFs of invoices (use `pdf` skill).
## Prerequisites
```
pip install opencv-python-headless pillow pillow-heif pytesseract reportlab numpy
# PyMuPDF is needed only to run the self-test (tests/), not the script itself
```
Plus system `tesseract-ocr` on PATH. Check with `tesseract --version`.
## Workflow (agent must follow the gate)
### Step 1 — scan
```bash
python3 ~/.hermes/skills/productivity/receipt-compiler/scripts/receipt_compiler.py \
scan <photos_dir> -o <workdir> [--mode bw|photo]
```
Default `--mode bw` gives the photocopy look the user asked for. Use `--mode photo`
for grayscale. Completion criterion: manifest exists with one entry per photo;
`ocr_confidence` and `needs_review` flags set.
### Step 2 — review + confirm (MANDATORY, user in the loop)
```bash
python3 .../receipt_compiler.py review <workdir>
# ... apply any corrections to manifest.json, THEN re-run review so the user
# ... sees the corrected table ...
python3 .../receipt_compiler.py review <workdir>
# ... after the user approves the corrected table ...
python3 .../receipt_compiler.py confirm <workdir>
```
Present the printed table to the user in chat. Ask:
1. Are the extracted dates/merchants/amounts right? Fix `manifest.json` fields.
2. Optional requirements — ask every time, do not assume:
- cover page (with claimant/period/notes)
- per-receipt numbering badges
- per-receipt captions (date · merchant · amount)
- currency symbol on totals
3. Exclusions — any receipt to drop (`"include": false`)?
4. Purpose/notes text for the cover.
Only after the user approves: run `confirm <workdir>`. This sets
`confirmed: true` AND binds a `review_digest` of the exact reviewed fields at
approval time. Any edit after `confirm` (dates, amounts, currency, inclusion)
makes `pack` refuse until you re-run `confirm` — which means showing the user
the changed table again. There is no bypass flag. Apply user corrections to
`manifest.json` BEFORE running `confirm`.
### Step 3 — pack
```bash
python3 .../receipt_compiler.py pack <workdir> -o claim.pdf \
[--cover --number --captions] \
--title "Expense Claim — <purpose>" --claimant "MH" --period "..." --notes "..."
```
Completion criterion: PDF exists, page count reported in JSON output.
Then send the PDF to the user as a document/file on the active channel.
## Layout rules (how receipts line up)
- A4 portrait, 15 mm margins, 5 mm gaps.
- Very tall receipts (aspect ≥ 2.2) are packed 3-per-row full-height;
normal receipts 2-per-row, capped at 52% of content height (≈47% of the
page). Scale is per-cell
(each receipt fills its cell); rows with fewer receipts get wider cells.
- Every image is scaled to preserve aspect ratio — no distortion, no cropping.
- Receipts flow across pages; 30+ receipts pack fine.
- Tall receipts print before normal ones; re-order via the manifest if needed.
## Common Pitfalls
1. **Skipping the confirmation gate** — `pack` hard-fails on `confirmed: false`,
non-boolean confirmation values, and post-confirmation edits (digest check).
There is no bypass flag; the user must see the table first.
2. **Dark/shadowed photos** — the 2/98 percentile stretch handles most; if OCR
confidence is < 55, or no amount was extracted, the entry is flagged
`needs_review`; surface these to the user.
3. **Perspective warp failure** — glossy/wrinkled receipts may not produce a clean
quad; the script falls back to small-angle deskew of the full frame. Check
`method` in the manifest; if `deskew` on a receipt that clearly needs
cropping, fix the crop manually with PIL or accept the framing.
4. **HEIC photos** — iPhone photos arrive as .heic; `pillow-heif` handles them if
installed. If missing, ask the user for JPGs or install `pillow-heif`.
5. **Multiple currencies** — totals are grouped per currency (review output and
cover page print one line per currency, no combined total). For a cleaner
claim, keep one currency per pack; never zero or edit valid amounts to force
a combined total.
6. **Long descriptions in cover table** — descriptions truncate at 70 chars; keep
cover notes short or put detail in `notes`.
## Verification Checklist
- [ ] `scan` produced manifest.json with an entry per photo
- [ ] `review` table shown to user; corrections applied to manifest
- [ ] Optional requirements asked each time (cover/numbering/captions)
- [ ] `confirm` run only after user approval (never hand-edit `confirmed`)
- [ ] `pack` output PDF exists, page count matches expectation
- [ ] PDF sent to the user with the correct output pathRelated skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |