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.

Important: Transaction Fields Use UUIDs

Transaction payee and category fields are UUIDs, not human-readable names. You MUST cross-reference them with actual_categories and actual_payees to get names.

Never grep transaction JSON for category or payee names — the names don't appear in the transaction records. Only imported_payee and notes contain free text, and these are unreliable (banks change formatting, Zelle shows generic "Zelle Transfer", etc.).

Searching by Category Name

To find transactions in a category (e.g., "Swim Lessons"):

# Step 1: Get the category UUID
source /home/node/.openclaw/workspaces/family-assistant/skills/finance/scripts/actual-helper.sh
actual_categories  # Find: {"id": "c830de67-...", "name": "Swim Lessons", ...}

# Step 2: Get transactions and filter by that UUID
actual_transactions "" "2024-01-01" "$(date +%Y-%m-%d)" \
  | python3 -c "
import sys, json
txns = json.load(sys.stdin)
cat_id = 'c830de67-...'  # from step 1
matches = [t for t in txns if t.get('category') == cat_id]
print(json.dumps(matches, indent=2))
"

Searching by Payee Name

To find transactions for a payee (e.g., "Aqua Warriors"):

# Step 1: Get the payee UUID
actual_payees  # Find the payee by name

# Step 2: Filter transactions by payee UUID
actual_transactions "" "2024-01-01" "$(date +%Y-%m-%d)" \
  | python3 -c "
import sys, json
txns = json.load(sys.stdin)
payee_id = 'f26f8469-...'  # from step 1
matches = [t for t in txns if t.get('payee') == payee_id]
print(json.dumps(matches, indent=2))
"

Date Range for Topic-Specific Queries

When the user asks about spending on a specific topic without specifying dates (e.g., "how much have we spent on swim lessons?"), search all-time (from 2024-01-01) rather than defaulting to the current month. Only use narrow date ranges when the user explicitly says "this month" or "in March".

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"

Two-step lookup — resolve category name to UUID, then filter:

# Step 1: Get the category UUID from actual_categories output
actual_categories  # find {"id": "abc123...", "name": "Groceries"}

# Step 2: Filter transactions by that UUID
actual_transactions "" "$(date +%Y-%m)-01" "$(date +%Y-%m-%d)" \
  | python3 -c "import sys,json; txns=json.load(sys.stdin); [print(json.dumps(t)) for t in txns if t.get("category")=="abc123..."]"

"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