spreadsheet-peek

spreadsheet-peek

Stop letting AI agents write throwaway Python just to look at a spreadsheet.

An agent-agnostic skill that teaches AI coding agents (Claude Code, Codex, Cursor, etc.) to use wolfxl peek for instant inline previews of .xlsx, .xlsm, .xls, .xlsb, .ods, .csv, .tsv, and comma-delimited .txt files - with proactive triggers, token-efficiency rules, readable date/number rendering, and format caveats baked in.

Before vs after - a naive agent writes throwaway Python every time; the same agent with spreadsheet-peek runs one wolfxl peek call:

Agent workflow demo - when a user mentions a spreadsheet path, the agent previews it first instead of guessing at the file shape:

Try it in 30 seconds

This is the fastest manual path. It is separate from the agent/plugin installs below.

cargo install wolfxl-cli
wolfxl peek examples/sample-financials.xlsx -n 10
wolfxl peek examples/sample-financials.xlsx --export text | sed -n '1,20p'

Why this exists

Without this skill, every agent reinvents spreadsheet inspection the same way:

# generated on-the-fly, run once, thrown away
import openpyxl
wb = openpyxl.load_workbook('data.xlsx', data_only=True)
ws = wb.active
for row in ws.iter_rows(max_row=10, values_only=True):
    print(row)

That means generated code, Python dependency startup, and raw tuple-dump output. Every. Single. Time.

With spreadsheet-peek, the agent runs wolfxl peek data.xlsx -n 15 instead:

• One reusable command instead of a fresh throwaway script
• Instant Rust-speed parsing (no openpyxl cold start)
• Readable output - dates render as ISO YYYY-MM-DD, common currency/percentage formats render in human-facing previews, and numeric cells are grouped for scanning
• Readable ASCII table the user can actually read
• Proactive triggers - the agent previews before processing, after fixture generation, and when you mention a file path, without being asked

Token efficiency (the part that's easy to miss)

Box-drawing output looks pretty but costs real tokens. The skill teaches the agent when to switch modes, with measurements taken against three sample shapes: a typical financial workbook (7 columns), a tall ledger (8 columns), and a wide operations dashboard (29 columns).

Sample	Mode	Command	Tokens (5 data rows)	Tokens/row
Financials (7 cols)	Box-drawing	wolfxl peek file -n 5	573	114.6
Financials (7 cols)	Text export	wolfxl peek file --export text | sed -n '1,6p'	148	29.6
Financials (7 cols)	Markdown export	wolfxl peek file --export markdown | sed -n '1,7p'	212	42.4
Tall ledger (8 cols)	Box-drawing	wolfxl peek file -n 5	624	124.8
Tall ledger (8 cols)	Text export	wolfxl peek file --export text | sed -n '1,6p'	173	34.6
Tall ledger (8 cols)	Markdown export	wolfxl peek file --export markdown | sed -n '1,7p'	217	43.4
Wide (29 cols)	Box-drawing	wolfxl peek file -n 5	2,249	449.8
Wide (29 cols)	Text export	wolfxl peek file --export text | sed -n '1,6p'	754	150.8
Wide (29 cols)	Markdown export	wolfxl peek file --export markdown | sed -n '1,7p'	962	192.4

~3.9x cheaper per row on typical financial shapes, ~3.6x on tall ledgers, ~3.0x on wide tables - but the absolute per-row savings is far larger on wide tables (299 tokens/row saved vs 85-90 on the narrower samples). Measured with cl100k_base (GPT-4 tokenizer) against examples/sample-financials.xlsx, examples/tall-ledger.xlsx, and examples/wide-table.xlsx. Reproduce with:

Markdown export is available in wolfxl-cli >= 0.9.0. Use it when a downstream context converter wants a Markdown table; keep text export as the default low-token repeat preview.

uv run --with tiktoken --with openpyxl python benchmarks/measure_tokens.py

The same benchmark now measures direct delimited inputs separately. A 7-column ledger costs 524 tokens in box mode and 145 tokens as text export for 5 rows across .csv, .tsv, and comma-delimited .txt; the quoted multiline CSV fixture costs 401 and 116 tokens. Those rows live in benchmarks/README.md so workbook ratios stay comparable.

Behavioral claims are smoke-tested separately with:

uv run --with openpyxl python benchmarks/verify_claims.py