Finance Receipt Analyzer

Description

--- name: finance-receipt-analyzer description: > Use this skill whenever the user wants to analyze receipts, track expenses, summarize spending, categorize purchases, or generate a financial summary spreadsheet from uploaded images or files. Trigger when the user mentions: receipts, expenses, spending summary, finance tracking, what they spent, income vs. expenses, expense categories, or uploads images of receipts/invoices. Also trigger when the user asks to "organize my finances", "track my spending", or "create an expense report". Always use this skill even if the user only uploads a single receipt image and asks a simple question about it. --- # Finance Receipt Analyzer Helps users analyze receipt images, extract spending data, and produce a professional Excel finance tracker with categorized expenses, totals, and an income/expense summary. --- ## Workflow Overview 1. **Ingest** — Accept uploaded receipt images (JPG, PNG, PDF) or a folder path 2. **Extract** — Use vision to read each receipt: merchant, date, items, amounts, subtotal, tax, total 3. **Categorize** — Assign each receipt a spending category 4. **Summarize** — Compute totals by category and overall 5. **Output** — Generate a formatted `.xlsx` finance tracker --- ## Step 1 — Ingest Receipts Receipts arrive as: - **Uploaded images** in the conversation (Claude reads them directly via vision) - **A folder path** (e.g., `/mnt/user-data/uploads/receipts/`) — list and process each file ```python import os from pathlib import Path receipt_dir = Path("/mnt/user-data/uploads/receipts") receipt_files = list(receipt_dir.glob("*.jpg")) + list(receipt_dir.glob("*.png")) + list(receipt_dir.glob("*.pdf")) ``` --- ## Step 2 — Extract Data from Each Receipt For each receipt image, extract the following fields using Claude's vision via the Anthropic API. Prompt template (see `references/extraction_prompt.md`): ```python fields_to_extract = { "merchant_name": str, # Store or vendor name "date": str, # ISO format: YYYY-MM-DD "items": list[dict], # [{description, quantity, unit_price, line_total}] "subtotal": float, "tax": float, "tip": float, # If applicable "total": float, "payment_method": str, # Cash, Visa, Mastercard, etc. "category": str, # See Category List below "currency": str, # Default: CAD "notes": str # Any unclear/ambiguous info } ``` **Handling unclear receipts:** - If total is illegible, sum line items + tax as fallback - If date is missing, use `"Unknown"` and flag it in the Notes column - If merchant name is unclear, use the partial text available + `"(partial)"` --- ## Step 3 — Spending Categories Assign one category per receipt. Use these standard categories: | Category | Examples | |---|---| | Groceries | Supermarkets, food stores | | Dining | Restaurants, cafes, fast food, delivery | | Transport | Gas, transit, Uber, parking | | Shopping | Clothing, electronics, Amazon | | Health | Pharmacy, clinic, gym | | Utilities | Hydro, internet, phone bill | | Entertainment | Movies, events, streaming | | Travel | Hotels, flights, Airbnb | | Office/Work | Supplies, software, tools | | Other | Anything that doesn't fit above | If the user provides custom categories, use those instead. --- ## Step 4 — Build the Excel Tracker Use `openpyxl` to build a multi-sheet workbook. See `references/excel_structure.md` for full column specs and formatting rules. ### Sheet 1: `Transactions` All individual receipts, one row per receipt. Columns: `Date | Merchant | Category | Items Summary | Subtotal | Tax | Tip | Total | Payment Method | Currency | Notes` ### Sheet 2: `Summary by Category` Pivot-style summary. Columns: `Category | Transaction Count | Total Spent | % of Total` — Uses Excel `SUMIF` and `COUNTIF` formulas referencing Sheet 1. ### Sheet 3: `Income & Balance` For users who provide income data. Rows: - Total Income (user-entered, blue text = hardcoded input) - Total Expenses (formula: `=SUM(Transactions!H:H)`) - Net Balance (formula: `=Income - Expenses`) - Savings Rate (formula: `=Net/Income`) ### Sheet 4: `Monthly Breakdown` *(optional, if date range spans multiple months)* Columns: `Month | Total Spent | Transaction Count` — Uses `SUMPRODUCT` + `TEXT` formulas to group by month. --- ## Step 5 — Formatting Requirements Follow the `xlsx` skill color conventions: - **Blue text**: User-entered inputs (income amount) - **Black text**: All formulas - **Header rows**: Dark background (`1F3864`), white bold text - **Alternating row shading**: Light grey (`F2F2F2`) on even rows - **Currency**: `$#,##0.00` format for all monetary columns - **Totals rows**: Bold, top border Always run `scripts/recalc.py` after building the file to validate formulas. --- ## Output Save the final file to `/mnt/user-data/outputs/finance_tracker.xlsx` and present it to the user. Include a plain-language summary in the chat: - Total spent across all receipts - Breakdown by top 3 categories - Any flagged issues (unreadable receipts, missing dates, etc.) - Prompt user to add income if Sheet 3 is empty --- ## Edge Cases | Scenario | Handling | |---|---| | Duplicate receipts | Flag rows with same merchant + date + total; add `(possible duplicate)` note | | Foreign currency | Preserve original currency in column; note conversion needed | | Multiple receipts in one image | Extract each separately as distinct rows | | No receipts uploaded | Ask the user to upload images or specify a folder | | PDF receipts | Extract text with `pdfplumber`; fall back to vision if text extraction fails | | Missing income data | Leave Sheet 3 inputs blank with placeholder label "Enter your income here" |

Security Status