budget-skill - SKILL.md Agent Skill

name: budget-skill description: SimpleFIN API integration for transaction tracking, spending categorization, budgeting, and financial reports. Use when user requests: connect bank account, fetch transactions, categorize spending, set/track budgets, review spending, or generate financial reports. Guide users through SimpleFIN setup, help generate personalized merchant rules, run budget commands, and provide spending analysis.

Budget Skill for Agents

This skill helps users connect their bank accounts, track spending, set budgets, and review transactions. Your role is to guide them through setup and use the skill to provide financial insights.

When to Use This Skill

Trigger when users ask about:

Connecting bank accounts
Tracking spending or transactions
Setting or checking budgets
Reviewing recent purchases
Generating spending reports
Financial accountability or savings goals

User Setup Flow

Step 1: SimpleFIN Account Creation

Guide the user to sign up for SimpleFIN ($2/month per bank):

"Go to https://beta-bridge.simplefin.org/"
"Click 'Create a SimpleFIN Bridge' and enter your email"
"You'll get a Setup Token (base64 string) — paste it here"

When they provide the token:

Base64 decode it to get the claim URL
Make a POST request to the claim URL to get the permanent Access URL
Save this Access URL for the next step

Step 2: Bank Connection

"Now connect your bank accounts via SimpleFIN's web interface:"

"Visit the setup URL from SimpleFIN"
"Search for your bank and enter your credentials"
"SimpleFIN will securely connect to your accounts"

This happens in their browser — you don't need to do anything.

Step 3: Skill Installation

Run the setup:

budget-skill setup

This creates:

Data directory: ~/.openclaw/workspace/data/simplefin/
Config file: config.json
Budget file: budgets.json

Step 4: Configure Access

Edit the config file with the Access URL from Step 1:

# Write to ~/.openclaw/workspace/data/simplefin/config.json
{
  "access_url": "https://USER:PASS@beta-bridge.simplefin.org/simplefin"
}

Step 5: Test Connection

budget-skill accounts

Should list all connected accounts with balances. If successful, guide them to fetch transactions:

budget-skill fetch --days 30

Personalized Merchant Rules

After initial setup, help users create personalized categorization rules.

Generate Personal Categories

Fetch recent transactions: budget-skill fetch --days 30
Load transaction data: ~/.openclaw/workspace/data/simplefin/transactions/transactions.json
Analyze recurring merchants, identify:
- Car loans (track balance)
- Subscriptions (monthly/annual)
- Personal services (gym, trainer)
- Payment plans
- Specific merchant names vs generic transfers
Create workspace/skills/budget-skill/personal-categories.json with:
- Merchant-specific rules
- Category mappings
- Balance tracking (for loans)
- Notes about frequency

Template structure:

{
  "merchant_rules": {
    "MERCHANT NAME": {
      "category": "CATEGORY",
      "notes": "Description",
      "frequency": "monthly",
      "track_balance": true,
      "current_balance": 0.00,
      "last_updated": "YYYY-MM-DD"
    }
  },
  "category_descriptions": { ... }
}

See personal-categories.example.json in the skill directory for full template.

Financial Context File (Optional)

For deeper context (especially for financial accountability), create: workspace/skills/budget-skill/financial-context.md

Include:

User's financial goals (saving for house, paying off debt, etc.)
Recurring payment details
Known merchant mappings
Budget preferences
Account balance history

Always read this file before generating reports to provide personalized, contextual advice.

Core Commands

All commands use the global budget-skill binary.

Fetch Accounts

budget-skill accounts

Returns all connected accounts with current balances. Run this before generating reports to get fresh data.

Fetch Transactions

budget-skill fetch --days 30

Pulls transactions from the last N days. SimpleFIN returns transactions nested in account responses, so this extracts and categorizes them.

Note: First-time bank connections may take 24 hours to populate transaction history.

Set Budget

budget-skill budget set --category FOOD_AND_DRINK --limit 500 --period monthly

Creates spending limits. Available periods: monthly, weekly

Check Budget Status

budget-skill budget status --period monthly

Compares actual spending vs budgets for current period. Highlights over-budget categories.

Generate Report

budget-skill report --period weekly

Shows spending breakdown by category, top merchants, and totals. Available periods: weekly, monthly

Providing Financial Insights

When analyzing spending:

Read context first: Check financial-context.md if it exists for user goals and preferences
Categorize accurately: Use personal rules to identify specific merchants
Flag wasteful spending: Highlight food delivery, expensive meals, unused subscriptions
Quantify impact: Show how cutting expenses affects savings goals
Be specific: "Uber Eats $45 this week" not "delivery expenses increased"

Report Structure

Weekly/Monthly Reports:

Total spending by category
Current account balances
Top merchants
Flags for wasteful spending
Actionable recommendations

Daily Reviews:

List today's transactions
Updated balances
Flag suspicious or unusual charges
Call out impulse purchases

Budget Accountability

If user has set financial goals (in financial-context.md or BUDGET.md):

Evaluate ALL spending through that lens
Calculate impact on savings goal (e.g., "$50 delivery = $50 less for down payment")
Be direct about wasteful spending
Track progress toward goals

Spending Categories

Personalized Categories (from personal-categories.json):

AUTO_LOAN - Car loan payments (track balance)
SUBSCRIPTIONS - Software/services
CREDIT_CARD_PAYMENT - Credit card autopay
SAVINGS - Investment contributions
PERSONAL_SERVICES - Personal trainer, services
PAYMENT_PLANS - Installment payments

Generic Categories (fallback):

FOOD_AND_DRINK
TRANSPORTATION
GENERAL_MERCHANDISE
ENTERTAINMENT
PERSONAL_CARE
TRAVEL
UTILITIES
HOUSING
TRANSFER
UNCATEGORIZED

Data Storage

All data lives in: ~/.openclaw/workspace/data/simplefin/

config.json - SimpleFIN Access URL (contains credentials)
accounts/accounts.json - Connected accounts
transactions/transactions.json - Categorized transactions
budgets.json - Budget limits by category

Security: All data is local. Access URL acts as password — never expose it.

Troubleshooting

"Config not found"
→ Run budget-skill setup first

"No transactions found"
→ Run budget-skill fetch --days 30

Empty transactions for a bank
→ Some banks take 24 hours to sync. Check again tomorrow.

Balance showing as cents instead of dollars
→ SimpleFIN returns balances as dollar strings, not cents. CLI should parse as-is.

"Please add your SimpleFIN Access URL"
→ Config file is missing the Access URL or still has placeholder text

Automated Reports

For recurring budget reviews, set up cron jobs:

Weekly Report (Sunday 7 PM):

{
  "schedule": {"kind": "cron", "expr": "0 19 * * 0", "tz": "America/Chicago"},
  "payload": {
    "kind": "agentTurn",
    "message": "Generate weekly budget report:\n1. Read financial-context.md\n2. Run: budget-skill accounts\n3. Run: budget-skill fetch --days 7\n4. Run: budget-skill report --period weekly\n5. Analyze spending, flag waste, provide recommendations"
  }
}

Daily Review (10 PM):

{
  "schedule": {"kind": "cron", "expr": "0 22 * * *", "tz": "America/Chicago"},
  "payload": {
    "kind": "agentTurn",
    "message": "Daily transaction review:\n1. Read financial-context.md\n2. Run: budget-skill accounts\n3. Review today's transactions\n4. Flag suspicious or wasteful spending"
  }
}

Best Practices

Always fetch fresh data before generating reports
Read financial-context.md for personalized insights
Update personal-categories.json when new recurring merchants appear
Track loan balances and report progress when payments appear
Be specific in recommendations — "Cut Uber Eats" not "reduce food spending"
Respect user goals — if saving for a house, evaluate all spending through that lens

Example Workflow

User asks: "How much did I spend this week?"

budget-skill accounts (refresh balances)
budget-skill fetch --days 7 (get recent transactions)
budget-skill report --period weekly (generate report)
Read financial-context.md (if exists)
Analyze output:
- Summarize spending by category
- Show top merchants
- Flag wasteful spending (food delivery, impulse buys)
- Compare to budget (if set)
- Provide actionable recommendations
Present findings in conversational format

References

SimpleFIN API: https://beta-bridge.simplefin.org/info/api
Repository: https://github.com/benminer/openclaw-budget-skill
Setup Guide: See README.md in skill directory