Family Finance Report Skill

DO write:

• First names only (when identifying card members or family)
• Merchant names (stripped of address fragments)
• Transaction amounts, dates, and categories
• Account type labels with last-4 only ("Checking ••1234", "Credit Card ••5678")
• Aggregated tax-relevant totals

When in doubt, redact. It is always safe to strip more than needed.

Supported File Formats

The skill handles these file types. When you encounter an unfamiliar format, read a sample and adapt — the Python script is designed to be extended.

Required Setup (do this ONCE before running the workflow)

The skill needs Python 3 with three libraries. Check if they're installed and install them if missing:

python3 -c "import openpyxl, pdfplumber" 2>&1
# If ModuleNotFoundError:
pip install openpyxl pdfplumber

Some users will have Python in a virtual environment. If pip install fails with "externally-managed-environment", guide them to create a venv or use pipx install. Do NOT suggest --break-system-packages.

Workflow: Step by Step

Step 1 — Inventory the folder

Ask the user for the folder path, then list its contents. Classify each file by likely source:

Looking at /path/to/folder, I found:
  📄 5 PDF files matching "*statements*" → credit card statements (Chase?)
  📊 3 XLSX files with "AMEX" in the name → AMEX card exports
  📋 2 JSON files with "Checking" in the name → bank account dumps
  ❓ 1 PDF file named "W2_2025.pdf" → probably tax form, skip

If you find files that look like tax forms (W-2, 1099, 1098) or ID documents, do not parse them. They contain SSNs and personal addresses.

Step 2 — Gather minimal context

Ask the user the following, one topic at a time so it doesn't feel like a form. Nothing here is optional for a high-quality report, but all of it is minimal and non-sensitive.

(a) Household members — first names only

"Whose finances are these? Give me first names only — something like 'Alex and Jamie' or just 'Alex' if you're solo."

(b) The year being analyzed

"Which tax year should I focus on? (I'll filter transactions to that calendar year — other years will be ignored.)"

(c) Tax filing structure

"What's your tax filing situation? Pick one:

• Single
• Married Filing Jointly (MFJ)
• Married Filing Separately (MFS)
• Head of Household (HoH)
• Qualifying Widow(er)"

This drives the correct standard deduction baseline, itemization threshold, and SALT cap behavior in the report insights.

(d) Dependents

"Any dependents? For each, give me just:

• First name (or nickname like 'youngest')
• Age or date of birth
• Relationship ('child', 'parent', etc.)
• Any special notes about them for the year (e.g., 'in preschool until August', 'starts college in fall', 'full-time caregiver')"

Ages and relationships are critical for tax credits:

• Child & Dependent Care Credit: kids under 13 only
• Child Tax Credit: under 17
• American Opportunity / Lifetime Learning: post-secondary students
• Qualifying Relative: other dependents supported by the household

(e) Any specific categorization corrections

"Are there any regular payments in your statements that might be categorized wrong by a generic tool? For example, a preschool that shows up as 'University' in the merchant name, or a recurring charge that's actually a business expense?"

Write any corrections into the family config's category_overrides section so they apply every year.

(f) Files to skip

"Any files in the folder I should ignore?"

Do NOT ask for:

• Full names
• Account numbers
• Tax ID / SSN
• Addresses
• Specific income amounts
• Employer details beyond "federal", "state", "university", "private"
• Anything else that could identify the household

Step 3 — Run the processing pipeline

Use the Python script at scripts/build_report.py (in this skill directory). The script takes a folder path and a JSON config file describing the family members and optional custom categorization rules.

python3 ~/.claude/skills/family-finance-report/scripts/build_report.py \
  --input-dir "/path/to/folder" \
  --output-dir "/path/to/folder" \
  --family-config "/path/to/folder/.family_config.json"

The script will:

1. Discover all supported files in the input directory
2. Parse each file with the appropriate parser
3. Strip PII (account numbers, addresses, phone numbers, last names)
4. Apply the categorization engine
5. Write transactions.csv (the analyzable dataset)
6. Write report_data.json (structured data for the HTML template)

Step 4 — Generate the HTML report

After the script produces report_data.json, use the template at templates/report_template.html as the starting point. The template contains placeholders like {{TOTAL_SPENDING}} that you fill in with real values. Save the final report as Finance_Report_{YEAR}.html in the same folder.

Important: The HTML should be a single self-contained file. Load Chart.js from CDN so the report works offline once loaded. Do not embed any external tracking or analytics.

Step 5 — Surface insights

After generating the raw report, read the CSV and look for non-obvious findings to add to the narrative. These are the insights that wow users:

• Savings rate leaks: Low-yield savings accounts (<0.5% APY) losing thousands to inflation. Compute what a HYSA at current rates would earn.
• Subscription creep: Total monthly recurring charges. Duplicates (two music services, two VPNs, etc.).
• Tax opportunities: Mortgage interest exceeding the standard deduction → should itemize. Medical spending above 7.5% of detected income → deductible portion.
• Spending personality: Top merchant by frequency, biggest single purchase, quietest month, busiest month.
• Family division of labor: Who pays for what (groceries, medical, entertainment). Don't moralize — just describe the pattern.
• Seasonal patterns: November/December spikes (holidays), back-to-school surges, tax-time refunds.

Step 6 — Present the outputs

Tell the user what you produced:

I generated three files in /path/to/folder:

1. transactions.csv — 1,851 categorized transactions, 99% coverage
   (open in Excel/Numbers for ad-hoc analysis)

2. Finance_Report_2025.html — interactive dashboard with charts
   (open in a browser; shareable with family)

3. report_data.json — structured data powering the report
   (keep for re-generation or custom analysis)

Here are the 3 most interesting findings:
- [finding 1]
- [finding 2]
- [finding 3]

Categorization Engine

The script ships with ~40 default merchant patterns covering common U.S. merchants (groceries, gas, dining, utilities, subscriptions, etc.). Aim for >95% categorization coverage. For the remaining uncategorized