Finance Skill#

Record and query personal financial data stored in PostgreSQL via the assistant CLI.

Commands Reference#

All commands: assistant <command> [json-args] Output: JSON to stdout on success, error to stderr with exit code 1.

CommandArgumentsDescriptioncreate-expenseamount, walletId, currencyCode, categoryId, description?Record an expensecreate-incomeamount, walletId, currencyCode, description?Record incomecreate-transferamount, walletId, currencyCode, toWalletId, toCurrencyCode, toAmount, description?Transfer between walletslist-transactionswalletId?, categoryId?, type?, limit?, offset?, dateFrom?, dateTo?List transactionsdelete-transactionidDelete a transactionget-wallets—Get all wallets with balancesget-wallet-balancewalletIdGet wallet balancecreate-walletnameCreate a walletget-categories—Get all categoriescreate-categorynameCreate a categorydelete-categoryidDelete a categoryspending-reportgroupBy, walletId?, dateFrom?, dateTo?Spending report

Transaction Types#

1. Expense (Трата)#

• Use assistant create-expense '{"amount":"100","walletId":"...","currencyCode":"ARS","categoryId":"..."}'
• Amount is always positive — the system negates it automatically
• Requires: amount, walletId, currencyCode, categoryId
• Optional: description

2. Income (Пополнение)#

• Use assistant create-income '{"amount":"5000","walletId":"...","currencyCode":"ARS"}'
• Amount is positive
• Requires: amount, walletId, currencyCode
• Optional: description

3. Transfer (Перевод)#

• Use assistant create-transfer '{"amount":"100","walletId":"...","currencyCode":"USD","toWalletId":"...","toCurrencyCode":"USD","toAmount":"100"}'
• The system creates two linked transactions automatically
• Requires: amount, walletId, currencyCode, toWalletId, toCurrencyCode, toAmount
• Optional: description
• For same-currency transfers, toAmount equals amount

Workflow#

Step 1: Parse the Request#

Extract from the user's message:

• Amount — number (always positive)
• Currency — currency code (e.g. ARS, RUB, USDT)
• Description — what was bought / reason for transaction (optional)
• Wallet — which wallet to use
• Category — spending category (required for expenses only)
• Type — expense, income, or transfer (infer from context)

Step 2: Resolve References#

Before creating a transaction:

1. Run assistant get-wallets to find the correct wallet ID
2. Run assistant get-categories to find the correct category ID
3. If category doesn't exist, ask the user or create it with assistant create-category '{"name":"..."}'

Step 3: Handle Ambiguity#

If any required field is unclear or missing, ask the user one concise clarifying question. Common cases:

• Wallet not specified and user has multiple wallets
• Category is ambiguous
• Amount is missing
• Transfer destination unclear

Do NOT guess — ask. But do NOT over-ask if the context is obvious.

Step 4: Create the Transaction#

Run the appropriate command ( assistant create-expense, assistant create-income, or assistant create-transfer) with the resolved data as a JSON argument.

Step 5: Report Back#

After creating the transaction, run assistant get-wallet-balance '{"walletId":"..."}' and reply with a concise confirmation including:

• What was created (description, amount, wallet, category)
• Updated wallet balance

Example reply format for an expense:

text

Записал: Булочка -200 ARS (Наличка ARS, Продукты)
Баланс Наличка ARS: 15 300 $

Example reply format for a transfer:

text

Перевод: 100 USD Tinkoff → Наличка
Баланс Tinkoff: 500 $
Баланс Наличка: 300 $

Constraints#

• NEVER create transactions without confirming ambiguous details first
• Always respond in the same language as the user's message (default: Russian)
• Keep responses short and action-oriented — no unnecessary explanations