spreadsheet-helper

---
name: spreadsheet-helper
description: Answers a plain-English question about a spreadsheet and shows the rows behind the number, so nobody writes a formula. Use for any .xlsx or .csv question, such as who still owes us money.
---

# Get answers out of a spreadsheet without writing a formula

Ask in plain English. Get one number, the rows behind it, and what the sheet cannot answer.

## Claude does

1. Get four inputs and refuse to start without them: file path, sheet name, the question in one sentence, and what one row means ("one invoice").
2. Read the header plus the first 20 data rows only. Print each column back with its meaning and type (date, money, text, category). The user corrects it before counting starts.
3. Turn every vague word into a column and a rule in writing. "Last month" becomes Date between 1 and 31 August. "Owed" becomes Status is not Paid. No rule means ask, never guess.
4. Name the blockers first: blanks, mixed currencies, dates stored as text, duplicates, merged headers. Use Anthropic's wording, "I do not have enough information to confidently assess this", rather than a tidy wrong number.
5. Temperature 0, Google's setting for tasks with one correct answer.
6. Data at the top of the prompt, question at the bottom: Anthropic measures up to 30 percent better answers, and quote-first grounding above 20,000 tokens.
7. Quote first: list the matching rows verbatim, then answer from those rows only. If none match, say "No relevant quotes found".
8. Retraction pass: every figure traces to a quoted cell, or it is deleted and the gap marked with empty [] brackets.

## Then Codex does

Codex takes the bulk arithmetic once the rules are fixed: opening the whole workbook, applying your filter to every row rather than the 20 you sampled, summing, grouping and writing an evidence file of matching rows. It is bulk mechanical work; a human slows and errs with every extra row. Fill in {FILE_PATH}, {SHEET_NAME}, {COLUMN_MAP}, {FILTER_RULES} and {QUESTION} inside CODEX.md, then run:

```
codex exec --sandbox danger-full-access --skip-git-repo-check -C "<working folder>" - < CODEX.md
```

## Claude checks

1. Rows counted plus rows skipped equals the file's row count. A silently dropped row is a defect.
2. Zero rows needs a control: the unfiltered count plus one row passing a loosened filter. "Nothing matched" is free and proves nothing.
3. Read the figures from the output file, never from a number you retyped.
4. Recompute one row by hand against Codex's line for it.
5. The answer names its sheet, column and row numbers.

Reject and rerun: any failed check goes back to Codex with the evidence. Never patch the number yourself.

## Rules

- Ask rather than guess a definition, a date boundary or a currency.
- Show the rows behind every figure.
- Report every skipped row with its reason; a swallowed error beats a silent one.
- Public information only.
- Never invent a fact, a number or a quote.
- Anything sent in someone's name says whose name it is.

## If Codex is not installed

Claude does the counting pass itself over the full file and says so.

## Built from

- anthropics/skills, https://github.com/anthropics/skills, 174,340 stars from api.github.com, home of the xlsx skill.
- Anthropic, Reduce hallucinations, https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-hallucinations, the refusal wording and the [] retraction pass.
- Anthropic, Prompting best practices, https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices, query-last worth up to 30 percent.
- Google and Kaggle, Prompt Engineering whitepaper by Lee Boonstra, https://www.kaggle.com/whitepaper-prompt-engineering, temperature 0 for single-answer tasks.

# Get answers out of a spreadsheet without writing a formula - Codex task

## You are given

- {FILE_PATH} the spreadsheet on disk, .xlsx or .csv.
- {SHEET_NAME} the single sheet to read. Ignore every other sheet.
- {COLUMN_MAP} each column that matters, with its meaning and type, already agreed with the user. Example: `Column D = invoice total, money, GBP`.
- {FILTER_RULES} the exact rules that decide whether a row counts, written as column plus comparison. Example: `Status is not Paid AND Date between 2026-08-01 and 2026-08-31`.
- {QUESTION} the one-sentence question in plain English, for context only. {FILTER_RULES} is what you implement.

## Produce

Three files in the working folder.

1. `answer.txt` - at most 5 lines. The headline figure, its unit or currency, the number of rows behind it, and the row count of the whole sheet.
2. `evidence.csv` - every matching row, with its original spreadsheet row number in the first column, followed by only the columns named in {COLUMN_MAP}. No re-ordering, no reformatting of values.
3. `skipped.csv` - every row you did not count, with its row number and one of these reasons: `blank in required column`, `unparseable date`, `unparseable number`, `duplicate of row N`, `filtered out`. Every row of the sheet appears in exactly one of evidence.csv or skipped.csv.

## Rules

- Read the file with openpyxl or pandas. Do not open it in an application and do not modify it. The source file must be byte-identical afterwards.
- Implement {FILTER_RULES} literally. If a rule is ambiguous, stop and print `AMBIGUOUS:` followed by the rule and what is unclear. Do not choose an interpretation.
- Never invent, infer or fill a value. A blank cell is blank and goes to skipped.csv.
- No bare exception handlers. Every failure logs the row number and the reason.
- Do not convert currencies. If a money column contains more than one currency symbol, stop and print `MIXED CURRENCY:` with the symbols and two example row numbers.
- Do not round until the final headline figure, then to 2 decimal places.
- Count rows once. Do not deduplicate unless {FILTER_RULES} says to.

## Return

Print to stdout, in this order:

1. `TOTAL ROWS: <n>` from the raw sheet, header excluded.
2. `MATCHED: <n>` and `SKIPPED: <n>`, and confirm they sum to TOTAL ROWS.
3. `ANSWER: <figure> <unit>`.
4. `CONTROL:` the count of rows matching {FILTER_RULES} with its date or status condition removed, so a zero result can be told apart from a broken filter.
5. `SAMPLE:` the first 3 lines of evidence.csv, verbatim.
6. The exact code you ran, so the arithmetic can be re-read rather than trusted.