actual-budget-skill/SKILL.md

name, description

name	description
actual-budget	Use when the user asks about finances, budget, spending, account balances, transactions, categories, or money. Triggers on questions like "how much did I spend", "what's my balance", "budget status", "spending breakdown", "net worth", or any financial query against the Actual Budget server.

Actual Budget Finance Skill

Query your Actual Budget instance for financial data — accounts, transactions, budgets, categories, and spending analysis. Read-only access.

Setup

Run the setup wizard (one-time):

SKILL_DIR=$(dirname "$(find ~/.claude -path '*/actual-budget/scripts/setup.sh' 2>/dev/null | head -1)")
bash "${SKILL_DIR}/setup.sh"

The wizard prompts for:

• Server URL — Your Actual Budget instance (default: https://budget.prettyhefty.com)
• Password — Server authentication password
• Budget sync ID — Selected from the list of available budgets

Configuration is stored in:

• ~/.config/actual-budget/config — Server URL, sync ID
• ~/.config/actual-budget/password — Server password (chmod 600)

Override the config directory by setting ACTUAL_BUDGET_CONFIG_DIR environment variable.

Using the Helper Functions

Source the helper script:

source "$(find ~/.claude -path '*/actual-budget/scripts/actual-helper.sh' 2>/dev/null | head -1)"

Available Functions

Configuration:

• actual_config — Show current configuration
• actual_check_config — Verify configuration is complete

Accounts:

• actual_accounts — List all accounts with current balances
• actual_balance [name] — Get balance for specific account (fuzzy match by name)

Budget:

• actual_budget_months — List all months with budget data
• actual_budget_month [YYYY-MM] — Budget summary for a month (defaults to current)

Transactions:

• actual_transactions [account] [start_date] [end_date] — List transactions (all accounts if none specified)
• actual_spending_by_category [start_date] [end_date] — Spending breakdown by category

Reference Data:

• actual_categories — List all categories
• actual_category_groups — List category groups
• actual_payees — List all payees
• actual_budgets — List budgets available on server

Advanced:

• actual_query '<json>' — Run an arbitrary ActualQL query

Output Format

All functions output JSON. Amounts are in decimal format (e.g., 123.45), not Actual's internal integer format.

Common Query Patterns

"How much did I spend this month?"

actual_spending_by_category "$(date +%Y-%m)-01" "$(date +%Y-%m-%d)"

"What's my balance across all accounts?"

actual_accounts

"Show me transactions for Groceries this month"

First get categories to find the ID, then query transactions and filter:

actual_categories  # find the category ID
actual_transactions "" "$(date +%Y-%m)-01" "$(date +%Y-%m-%d)"  # then filter by category in the JSON output

"Am I over budget this month?"

actual_budget_month "$(date +%Y-%m)"

The result includes budgeted, spent, and balance per category.

"What did I spend at [payee] recently?"

actual_transactions "" "2026-01-01" "$(date +%Y-%m-%d)"

Then filter the JSON output by payee name.

ActualQL Quick Reference

For complex queries, use actual_query with a JSON query object:

actual_query '{"table":"transactions","filter":{"date":{"$gte":"2026-03-01"}},"select":["date","amount","payee","category"]}'

Operators: $eq, $lt, $lte, $gt, $gte, $ne, $regex, $like, $oneof, $and, $or

Tables: transactions (primary), plus accounts, categories, payees accessible via the helper functions.

Troubleshooting

• "Config not found" — Run setup.sh
• "@actual-app/api not installed" — Run cd <skill-scripts-dir> && npm install @actual-app/api
• Connection errors — Check server URL and password in ~/.config/actual-budget/config
• Empty results — Verify the sync ID matches an active budget (actual_budgets)

Presentation Guidelines

• Format currency with dollar signs and commas ($1,234.56)
• Amounts are already in dollars — do not divide by 1000
• Highlight categories over budget
• Summarize before showing details — lead with the key insight
• For transaction lists, show date, payee, category, and amount in a clean table
• When computing frequency ("how often"), count unique dates, not transaction count
• Verify arithmetic before presenting — sanity-check that "X out of Y" values are logically possible
• Prefer concrete numbers over vague summaries

Privacy

• Financial data is private to the family
• Present data matter-of-factly without judgment
• Do not modify transactions unless explicitly requested by Bill