Agent Skills
These documents are intended for AI agents and teach your agent how to manage your budget. See the Quickstart guide for setup instructions.

Workflow: Budget Optimization

The user connected fscl to an existing Actual Budget. Accounts, transactions, and categories already exist, but fscl automation (rules, payee cleanup) hasn't been set up. Your job: audit the current state, clean it up, and build automation.

Step 1: Audit Current State

Gather the full picture:

bash
fscl accounts list --json
fscl categories list --json
fscl transactions uncategorized --json
fscl transactions reconcile list --json
fscl payees stats --extended --json
fscl rules list --json
fscl month status --json

Assess and report to the user:

  • How many accounts? Are balances reasonable?
  • How many categories? Any duplicates or obvious gaps?
  • How many uncategorized transactions?
  • How many unreconciled transactions?
  • How many payees? Are there messy bank names?
  • Any rules already set up?
  • Current budget status — is money allocated?

Present a summary: "Here's what I found in your budget. I have some suggestions to clean things up — want to go through them?"

Step 2: Category Cleanup

Compare against templates in budgeting.md — don't force a template, but use it to spot gaps.

Look for:

  • Duplicates (e.g., "Food" and "Foods") → merge: fscl categories delete <dup-id> --transfer-to <keep-id> --yes
  • Empty groups → delete if unused
  • Missing categories → suggest additions based on transaction patterns
  • Miscategorized income → ensure income categories have the --income flag

Confirm changes with the user before making them.

Step 3: Payee Cleanup

Use payee stats to find the worst offenders:

bash
fscl payees stats --extended --json

Look for:

  • Multiple payees for the same merchant (e.g., "AMZN MKTP US", "AMAZON.COM", "AMZN DIGITAL")
  • Ugly bank names that should be human-readable

Rename and merge:

bash
fscl payees update <id> --name "Amazon"
fscl payees merge <amazon-id> <amzn-mktp-id> <amzn-digital-id>

Step 4: Process Uncategorized Transactions

If transactions.uncategorized > 0, work through them:

bash
# Categorize (payee names are now clean from Step 3)
fscl transactions categorize draft
# Fill in category IDs using _meta context
# Do not create categorize.json manually; edit the generated draft file
fscl transactions categorize apply

For large backlogs, use --limit to work in batches:

bash
fscl transactions categorize draft --limit 50

Step 5: Create Rules

After cleaning payees and categorizing, build rules for recurring patterns so future imports auto-categorize.

Use the draft/apply pattern:

bash
fscl rules draft
# Edit rules.json — add new rules (no id field), update existing (with id)
fscl rules apply
fscl rules run --and-commit

For high-volume payees with name variations, create pre-stage rules:

bash
fscl rules create '{
  "stage": "pre",
  "conditionsOp": "and",
  "conditions": [{"field": "imported_payee", "op": "matches", "value": "AMZN|AMAZON"}],
  "actions": [{"field": "payee", "op": "set", "value": "<amazon-payee-id>"}]
}'

See rules.md for the full schema (conditions, actions, stages).

Step 6: Reconcile Reviewed Transactions

If transactions.unreconciled > 0, reconcile reviewed transactions in batches:

bash
fscl transactions reconcile draft --limit 50
# Remove entries that are not reviewed yet
fscl transactions reconcile apply

Use --account, --start, and --end when matching a bank statement.

Step 7: Review Budget Amounts

Compare actual spending to budgeted amounts:

bash
fscl month status --compare 3 --json

Suggest adjustments for categories that are consistently over or under budget.

If the budget has no amounts set for the current month, offer to set them up using the approach in workflow-onboarding.md Step 4.

Step 8: Credit Card Check

If any accounts have negative balances (credit cards), verify the setup:

  • Paying in full monthly? No special setup needed — purchases use regular expense categories.
  • Carrying debt? See credit-cards.md for rollover category + carryover setup.

Verify transaction signs

If credit card transactions were imported from OFX/QFX files, spot-check that purchases are negative (outflow) and payments are positive (inflow). Some bank exports have inconsistent signs. See import-guide.md for fix procedures.

Link payment transfers

If both checking and credit card accounts have been imported, payment entries likely exist on both sides as unlinked standalone transactions. Link them as transfers — see credit-cards.md "Linking payments when both accounts are imported."

Verify rules are account-scoped

Review existing rules that match on imported_payee alone. If a payee (e.g., Google, Apple, PayPal) appears on multiple accounts with different meanings, add an account condition to prevent miscategorization. See rules.md "Rules match across all accounts by default."

What's Next

Once optimization is complete, tell the user:

  • "Your budget is cleaned up! I've set up rules so future imports will auto-categorize most transactions."
  • "Going forward, import new transactions periodically and I'll handle the rest."
  • "At the start of each month, we'll review spending and set the next month's budget."