Monthly Budget Report

A comprehensive monthly financial reporting skill that processes bank and credit card transactions to generate category-level expense breakdowns, income summaries, savings rate calculations, and forward-looking projections. Works with CSV exports from any bank, YNAB, Mint, or direct statement imports.

Supported Platforms & Integrations

Platform	Setup Method	Auth Type	Notes
YNAB (You Need A Budget)	API key in config	REST API	Full budget data with category mapping
Mint / Credit Karma	CSV export	Local file	Transaction history export
Chase / Bank of America	CSV/OFX export	Local file	Statement downloads from online banking
Apple Card	Monthly statement CSV	Local file	Apple Wallet export or Goldman Sachs PDF
Google Sheets	Service account	OAuth2	Logs monthly summaries for multi-year tracking
Plaid	API keys	OAuth2	Automatic bank connection for transaction pull

When to Use This Skill

• Use this at the start of each month to understand exactly where last month's money went
• Use this when you feel like you spent more than usual but cannot pinpoint which category increased
• Use this when you want to track savings rate progress toward a specific financial goal
• Use this when you need to create a spending forecast for an upcoming large expense month
• Use this when you want to compare seasonal spending patterns across the same month in prior years
• Consider alternatives when you need real-time transaction alerts — use your bank app notifications instead
• Consider alternatives when you need investment portfolio analysis — this covers cash flow only, not asset allocation

Quick Start

Copy
# ~/.claude/skills/monthly-budget-report.yaml
data_sources:
  - type: csv
    path: ~/Finance/chase_checking.csv
    account: "Chase Checking"
  - type: csv
    path: ~/Finance/amex_credit.csv
    account: "Amex Credit Card"
income_sources:
  - employer_direct_deposit
  - freelance_invoices
categories:
  housing: ["rent", "mortgage", "property tax"]
  groceries: ["whole foods", "trader joe", "grocery", "safeway"]
  dining: ["restaurant", "doordash", "uber eats", "grubhub"]
  transport: ["gas", "uber", "lyft", "parking", "transit"]
  subscriptions: ["netflix", "spotify", "adobe", "gym"]
  utilities: ["electric", "water", "internet", "phone"]
currency: USD
savings_goal_rate: 0.20
history_file: ~/.finance/monthly_history.json

First Run Example

Copy
claude skill monthly-budget-report --month 2026-02

Expected Output

Monthly Budget Report — February 2026
=======================================

INCOME
  Salary (net):           $5,240.00
  Freelance:                $850.00
  Total Income:           $6,090.00

EXPENSES BY CATEGORY
  Housing:                $1,800.00  (29.5%)
  Groceries:                $412.38  (6.8%)
  Dining Out:               $287.50  (4.7%)
  Transportation:           $198.20  (3.3%)
  Subscriptions:            $127.94  (2.1%)
  Utilities:                $215.60  (3.5%)
  Shopping:                 $342.15  (5.6%)
  Health/Medical:            $85.00  (1.4%)
  Entertainment:            $156.00  (2.6%)
  Uncategorized:             $78.43  (1.3%)
  Total Expenses:         $3,703.20  (60.8%)

SAVINGS
  Amount Saved:           $2,386.80
  Savings Rate:           39.2% (goal: 20%) -- exceeding target
  Emergency Fund:         $12,400 (4.1 months of expenses)

MONTH-OVER-MONTH
  Income:    +$850 (+16%) -- freelance project income
  Expenses:  +$310 (+9%) -- shopping spike
  Savings:   +$540 (+29%)

NOTABLE TRANSACTIONS
  Largest expense: $1,800.00 — Rent
  Largest non-recurring: $189.99 — Electronics (headphones)
  Smallest category: Health ($85.00)

NEXT MONTH PROJECTION
  Expected income: $5,240 (salary only, no freelance invoiced)
  Projected expenses: $3,450 (based on 3-month average)
  Projected savings rate: 34%

7 transactions uncategorized — review and assign categories.

Advanced Configuration

Platform-Specific Setup

YNAB Integration

Copy
ynab:
  enabled: true
  api_key: "your-ynab-api-key"
  budget_name: "My Budget"
  use_ynab_categories: true
  include_goal_progress: true
  reconciled_only: false

Multi-Bank CSV Setup

Copy
csv_parsing:
  date_format: "MM/DD/YYYY"
  amount_column: "Amount"
  description_column: "Description"
  debit_is_negative: true
  skip_header_rows: 1
  encoding: utf-8
  chase_format:
    date_col: 1
    description_col: 2
    amount_col: 3
  amex_format:
    date_col: 0
    description_col: 3
    amount_col: 7

Full Options Reference

Parameter	Type	Default	Description
data_sources	list	[]	Bank/card CSV files or API connections
income_sources	list	[]	Keywords to identify income transactions
categories	map	default set	Category name to keyword mapping for auto-classification
currency	string	USD	Currency symbol and formatting
savings_goal_rate	float	0.20	Target savings rate as decimal (0.20 = 20%)
history_file	string	~/.finance/monthly_history.json	Path for storing historical data
include_projections	bool	true	Generate next-month spending forecast
rolling_average_months	int	3	Months used for trend and projection calculations
flag_uncategorized	bool	true	Highlight transactions that could not be auto-categorized
large_purchase_threshold	float	100	Dollar amount above which transactions are flagged as notable
exclude_transfers	bool	true	Exclude account-to-account transfers from expense totals
output_format	string	terminal	terminal, markdown, csv, or google_sheets
compare_to_budget	bool	false	Compare actuals against a predefined monthly budget

Core Concepts

Concept	Purpose	How It Works
Auto-Categorization	Reduces manual sorting	Matches transaction descriptions against keyword rules to assign categories
Savings Rate	Key financial health metric	Calculates (income - expenses) / income as a percentage
Rolling Projections	Forecasts next month	Uses 3-month average spending by category to predict upcoming month
Transfer Detection	Prevents double-counting	Identifies matching debits/credits between accounts and excludes from expenses
Uncategorized Flagging	Improves accuracy over time	Highlights transactions that did not match any rules for manual review

Architecture

Data Sources (CSV exports / YNAB API / Plaid)
                    |
                    v
          +--------------------+
          | Transaction Parser |----> Normalizes all formats to unified schema
          +--------------------+
                    |
                    v
          +--------------------+
          | Categorizer Engine |----> Matches descriptions to categories
          +--------------------+
                    |
          +---------+---------+
          |         |         |
          v         v         v
  +----------+ +----------+ +-----------+
  | Income   | | Expense  | | Savings   |
  | Summary  | | Breakdown| | Calculator|
  +----------+ +----------+ +-----------+
          |         |         |
          v         v         v
  +-------------------------------+
  | Report Generator              |
  | + Projections + Comparisons   |
  +-------------------------------+
              |
              v
  +-------------------------------+
  | History Logger + Export       |
  +-------------------------------+

Workflow Examples

Scenario 1: Spending Spike Investigation

Input: February expenses $310 higher than January

Processing:
  - Compares category-level spending month-over-month
  - Identifies Shopping category up $245 (3 Amazon orders, 1 electronics purchase)
  - Identifies Dining up $65 (Valentine's Day dinner + 2 extra takeout orders)
  - All other categories within normal range

Output:
  Expense Spike Analysis:
  Shopping: +$245 (one-time electronics purchase of $189.99 + 2 misc Amazon orders)
  Dining: +$65 (Valentine's dinner $95 was the driver)
  Verdict: Non-recurring spike. March should normalize to ~$3,400
  No structural spending increase detected

Scenario 2: Annual Expense Summary

Input: Run with --annual flag for 2025 full year

Processing:
  - Aggregates all 12 monthly reports
  - Calculates annual totals, averages, and highest/lowest months
  - Identifies seasonal patterns (holiday spending, summer travel)

Output:
  2025 Annual Financial Summary:
  Total Income: $68,400 | Total Expenses: $42,180 | Total Saved: $26,220
  Annual Savings Rate: 38.3%
  Highest expense month: December ($4,890 — holiday gifts + travel)
  Lowest expense month: September ($2,980)
  Biggest category: Housing at $21,600 (51% of expenses)
  Fastest growing: Subscriptions (+18% year-over-year)

Scenario 3: Budget vs Actual Comparison

Input: Monthly budget defined in config, February actuals imported

Processing:
  - Compares each category actual vs budgeted amount
  - Calculates variance and percentage over/under
  - Ranks categories by largest over-budget amounts

Output:
  Budget vs Actual — February 2026:
  Category        Budget    Actual    Variance
  Groceries       $400      $412      -$12 (3% over)
  Dining          $200      $288      -$88 (44% over) ** FLAG
  Shopping        $150      $342      -$192 (128% over) ** FLAG
  Transport       $200      $198      +$2 (on target)
  Entertainment   $100      $156      -$56 (56% over) ** FLAG
  Overall: $310 over total budget (driven by shopping one-time purchase)

Best Practices

1. Download statements on the same day each month — Consistency in timing prevents missing transactions that post late. Set a recurring reminder for the 2nd of each month to download all statements from the prior month.

2. Refine your category keywords after month one — The auto-categorizer improves as you add merchant-specific keywords. Every uncategorized transaction is an opportunity to add a new keyword so it is caught automatically next month.

3. Separate fixed from variable expenses mentally — Housing, utilities, and insurance are fixed. Groceries, dining, and entertainment are variable. Focus your reduction energy on variable categories where you have real control.

4. Track savings rate, not just expenses — Expense tracking alone creates anxiety. Savings rate as a percentage gives you a single, motivating number that captures the full picture of income minus outflow.

5. Use the projection as a planning tool — If next month has a known large expense (annual insurance, vacation), add it to the projection manually so you can plan savings adjustments in advance.

Common Issues

1. CSV columns do not match expected format — Use the csv_parsing config section to specify which columns contain date, description, and amount for each bank. Different banks use different column orders and headers.

2. Transfers between accounts counted as expenses — Enable exclude_transfers and add transfer keywords like "transfer", "payment from", or your account nicknames to the exclusion list.

3. Venmo and PayPal transactions lack detail — These services show as a single merchant name regardless of what you paid for. Add a manual_overrides section in config to reclassify specific Venmo transactions by amount and date.

Privacy & Data Handling

All financial data is processed entirely on your local machine. Bank CSV files are read from your specified paths and parsed in memory only. Transaction data, category mappings, and monthly summaries are stored in ~/.finance/monthly_history.json on your local filesystem and are never transmitted externally. No banking credentials are stored by this skill — it works with exported files, not direct bank logins. If YNAB integration is used, data flows from YNAB's API to your machine using your personal API key. Google Sheets export writes only to your own spreadsheet. You can delete all financial history by removing the ~/.finance/ directory at any time.