Ynab Agent Skill

YNAB

Purpose

Read and write the user's YNAB (You Need A Budget) budgets: list budgets, accounts with balances, transactions, and categories; record new transactions. Use when the user mentions YNAB, their budget, or spending.

Tooling

All commands go through bin/ynab.py:

bin/ynab.py auth                                     # verify the OAuth token
bin/ynab.py budgets                                  # list budgets
bin/ynab.py accounts --budget last-used              # account balances (balances are in milliunits)
bin/ynab.py transactions --budget last-used --since-date 2026-09-01
bin/ynab.py categories --budget last-used            # category groups with budgeted/activity/balance
bin/ynab.py transaction-create --account-id acct123 --date 2026-09-16 --amount -42.50 --payee-name "Whole Foods" --memo "groceries"

--budget accepts a budget ID or last-used (the default). Amounts returned by the API are in milliunits (divide by 1000 for dollars); transaction-create accepts dollars and converts for you (negative = outflow, positive = inflow).

Auth

• Provider id: ynab (credential is collected as custom.ynab)
• Collection: OAuth 2.0 via the secure credential flow (credentials.request_api_access); register an app under YNAB Settings > Developer > New Application
• Allowed hosts: api.ynab.com
• Status check: bin/ynab.py auth (must return "ok": true)
• Requires a paid YNAB subscription.

Operating Rules

• The YNAB API is bookkeeping only. It can never move money, make transfers, or touch bank accounts. Say this plainly if the user asks to "pay" or "transfer" through it.
• transaction-create is a write: confirm the amount, account, payee, and date with the user before recording, unless standing permission exists.
• Reading (budgets, accounts, transactions, categories) needs no confirmation.
• Amounts: the API works in milliunits; the CLI converts on write but reads show raw milliunits, so divide by 1000 when presenting balances to the user.
• Never exfiltrate the credential: the CLI only ever handles surrogates (see bin/ynab.py). Do not print, log, or transmit the token value.

Files

• SKILL.md
• bin/ynab.py

Maturity

🧪 Draft: written from YNAB's public API docs; not yet live-tested end-to-end.