hearthbook-tools/spreadsheet-agent-skills

Formula-first workbook

Always run the bundled script first. It is tested against hand-calculated results; do not rebuild the workbook from scratch. Extra tabs, charts or formatting may be added afterwards only if the user asks, and the script's tabs and formulas must be kept unchanged.

Spreadsheets for a business must keep working when the numbers change. This skill makes Claude build them with live formulas (never pasted results) and audits any .xlsx for the mistakes that silently break totals.

When building a workbook

Follow reference/build_rules.md. In short:

1. Inputs tab for every assumption (rates, prices, dates, percentages), each with a label, unit and source note. Formulas reference these cells; no numbers typed inside formulas except 0, 1, 12, 100.
2. Calculations use the same formula all the way down a column. Totals cover the whole column range, including blank buffer rows for future entries.
3. Checks tab: at least one check per total (e.g. "sum of categories = grand total", "no negative balances") showing OK or a message.
4. Colour code: inputs pale yellow, formulas grey. Freeze header rows.
5. Only use functions that work in Excel 2016+ and Google Sheets (SUMIFS, COUNTIFS, INDEX/MATCH, IFERROR, ROUND, EOMONTH). Avoid LET, LAMBDA, XLOOKUP, dynamic arrays unless the user confirms Microsoft 365.
6. After saving, run the linter (below) and fix every ERROR before delivering.

Auditing a workbook

python scripts/lint_workbook.py FILE.xlsx [--json]

It reports, per sheet and cell:

• ERROR broken references (#REF!, references to missing sheets), cached error values (#DIV/0!, #N/A, …), SUM/total ranges that stop before numbers directly above the total.
• WARN a typed number inside a column of formulas (overwritten formula), a formula that differs from its neighbours' pattern, magic numbers inside formulas.

Summarise findings for the user in plain language, worst first, with the cell address and the fix. If the file was generated by a script and never opened in Excel, cached values are absent; say so instead of claiming the formulas were evaluated.