# Beancount Ask > Answer questions about a beancount ledger with BQL queries — spending, trends, net worth, burn rate, subscriptions, anomalies. Use this skill whenever the user asks an analytical/reporting question about their ledger — "how much did I spend on groceries last month", "what's my net worth", "what subscriptions am I paying for", "did anything unusual happen in May", "what's my monthly burn" — or asks for a spending report/summary. Every figure in an answer comes from a bea --json query run the user can see and re-run (bean-query only when bea is unavailable); the skill is strictly read-only. SKIP when the user wants to record transactions (beancount-options / beancount-import), reconcile against a statement (beancount-reconcile), migrate from another app (beancount-migrate), edit the ledger in any way, or asks how beancount/BQL works in general (that's a docs question, not a query over their data). The core trigger is "answer this question from my ledger's data". - Skill: `bex-co/beancount-ask` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add bex-co/beancount-ask` - Raw SKILL.md: https://api.skillmd.com/api/skills/bex-co/beancount-ask/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: bex-co (https://skillmd.com/u/bex-co) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/bex-co/beancount-ask --- # beancount-ask Answer ledger questions with **shown, re-runnable BQL** — never with model arithmetic. This skill exists because a fluent-but-unverifiable answer about money is worse than no answer: the entire credibility of plain-text accounting is that every number is reproducible. So the contract is: every figure cited comes from a shown query execution, the query is shown with the answer, and the ledger is never modified. Prefer `bea` for reads when installed, fall back to bean-* only when `bea` is absent — stated once here, not repeated below. ## Scope **Does:** run read-only BQL against local ledger files; interpret results; show the query with every figure. **Does not:** write, edit, or format any file; guess or estimate when data is missing; answer general "how does beancount work" questions (point at docs); compute figures in-model (the query engine computes, the skill interprets). ## Workflow ### 1. Discover Find the main ledger file (same procedure as the sibling skills: `fd -e beancount -e bean .`, main = the file with `option`/`include` directives). Confirm which file when ambiguous. Tooling, in order of preference: 1. `bea --file --json query ""` — when `bea` is installed (managed engine runs Beanquery). Drop `--json` when reading the table yourself. `bea --file --json balance` gives the pruned trial-balance subtree, and `bea list transaction --search/--tag/--link` finds entries without BQL. Do not `pip install beanquery` or configure private engine paths while `bea` is present; if the engine fails, repair/retry provisioning rather than switching to a global `bean-query`. 2. Without `bea`: `bean-query ""` if a developer environment already provides it; otherwise suggest installing `bea`. 3. For polished statements (income statement, balance sheet trees), `bea --file report income-statement` beats raw BQL — say so rather than rebuilding them in BQL. 4. Optional quotes: `bea price …` needs `bea engine enable beanprice` first; recording a known quote uses `bea add price` without that feature. ### 2. Translate the question Map the question to a recipe in `references/bql-recipes.md` — **read it first; every query there is tested**. Establish the period explicitly: "last month" etc. resolves against today's date; state the resolved date range in the answer. If the question is ambiguous ("how much do I spend?" — period? category? average or total?), **ask, don't assume** — a precise answer to the wrong question reads as authoritative and misleads. ### 3. Run, then answer Run the query. Answer format: - **Lead with the figure(s)**, in a sentence or small table. - **Show the query** underneath (collapsed/quoted is fine) so the user can re-run or refine it. - **Say what the data can't show** when relevant (e.g. "transfers excluded; card payments are not spending"). - Point at the matching **Fava view** for browsing (Income Statement / Balance Sheet / Journal with a filter) when one exists. Interpretation rules (the classic sign traps are in the recipes reference): Income accounts accumulate negative; Expenses positive; `cost(position)` for USD totals; transfers and credit-card payments are **not** spending — recipes exclude them by selecting `^Expenses:` only. ### 4. When the data can't answer Missing period, no such account/payee, ledger doesn't track it (e.g. market values without price directives): say exactly what's missing and what would make it answerable. **Never estimate.** If the answer needs a write (adding price directives, opening accounts), that's another skill's job — name it and stop. ## What NOT to do - Don't state any figure that didn't come out of the query you show. - Don't modify, format, or "fix" any file — read-only, no exceptions. - Don't answer an ambiguous question by picking an interpretation silently. - Don't rebuild Fava's statements in BQL when pointing at Fava/`bea report` serves better. - Don't extrapolate ("at this rate you'll…") without labeling it as arithmetic on top of queried figures — and keep even that minimal.