Spreadsheet Import
Turn a spreadsheet into live app data: Data entries, Property Bank values, or
data-calculation sources.
Announce at start: "I'm using the xlsx skill to import this spreadsheet."
Step 1: Inspect
Run the bundled parser in listing mode to see sheets, sizes, and a first-row
preview. Resolve the script path against this skill directory (the directory
containing this SKILL.md) and pass the absolute path to bun as a single
command — no pipes, redirections, or chained shell commands. The script has
zero dependencies and runs fully offline.
bun /absolute/path/to/xlsx/scripts/xlsx_to_json.ts --list path/to/file.xlsx
Confirm with the user which sheet and columns matter when there is more than
one plausible target. Watch for: header rows that don't start at row 1, merged
cells, unit rows under headers, and trailing summary rows.
Step 2: Parse to structured rows
bun /absolute/path/to/xlsx/scripts/xlsx_to_json.ts --sheet "Menu" --header-row 2 --out output/import/menu.json path/to/file.xlsx
The output is { source, sheet, headerRow, columns, rowCount, rows } with
typed cells. Rules the script applies:
- Dates: spreadsheet serial numbers become ISO strings (
--dates serial
keeps raw numbers). Verify one sample date against the source before
importing — date detection is heuristic.
- Formulas: the last computed value is exported, never the formula.
- Empty cells become
null, not "".
- Merged cells: the value lands in the top-left cell; add
--fill-merged
to copy it across the merged range.
- CSV/TSV files parse directly; strings with leading zeros stay strings.
For very large sheets, parse is capped at 5000 rows by default — confirm the
shape on the first rows, then re-run with --limit 0 for everything.
Step 3: Choose the destination
| Content |
Destination |
Why |
| Values edited rarely, used in one place (title, phone, prices on one board) |
Brick properties / Property Bank values |
simplest; no indirection |
| Lists and tables the UI iterates (menu items, rooms, products) |
Data entries (project Data, edited with edit_entry) |
structured; drives list UIs |
| Content users will search or ask questions about |
vectorStore ingestion (see ai-recipes doc-qa pattern) |
semantic search / RAG |
| Data that must update on devices without redeploy |
Data Bank (cloud data via the dataBank generator) |
live updates to the fleet |
Default for tabular data: Data entries. Ask the user only when the destination
changes the app's structure.
Step 4: Import
- Data entries: use the
edit_entry tool (Data type). Derive stable keys from
a natural column (SKU, item name) — not from row order — so re-imports
update instead of duplicate.
- Shape rows to what the UI needs before importing: rename columns to
property names (the script's
columns[].key mapping is the starting
point), coerce types, drop unused columns.
- Keep the parsed JSON in
output/import/ — it records the source file,
sheet, header row, and column mapping, which makes the import reviewable
and repeatable.
Step 5: Verify
Preview in the simulator: the list UI renders every row; spot-check first,
last, and one middle row against the source file. Check type-sensitive
displays: dates, currency, decimals, phone numbers.
Re-import (the sheet changed)
- Re-run Step 2 with the same flags (they are recorded in the previous JSON).
- Diff old vs new JSON; report added/removed/changed keys to the user.
- Update Data entries by stable key; never wholesale-delete unless asked.
Runtime ingestion (apps that accept sheets while running)
For apps that must ingest user-uploaded files at runtime, don't parse at
design time — wire the app itself:
- The
vectorStore generator's insert-file command ingests Office/OpenOffice
documents into searchable chunks (works on all launchers).
- Data calculations can call
parseDocument(path) for text extraction.
Both give text, not structured cells — for structured runtime data,
prefer the Data Bank flow (update data in the cloud, devices subscribe via the
dataBank generator) over runtime file parsing.
Guidelines
- Sample before bulk: for files with thousands of rows, parse 20 rows first
(
--limit 20), confirm the shape with the user, then run the full import.
- Numbers displayed as text (leading zeros, phone numbers) must stay strings —
respect the source column formatting.
- Multi-sheet workbooks: one logical table per destination; don't merge
unrelated sheets into one Data list.
When Not To Use
- The deliverable is a spreadsheet file (creating/editing .xlsx) — out of scope.
- The file is a PDF, Word document, or slide deck — use the
pdf / docx /
pptx skills.
- Tiny one-off values (a single number) — just set the property directly.
1---2name: xlsx3description: Use when the user brings a spreadsheet (.xlsx, .csv, .tsv) into their BRICKS project and wants its data in the app — product lists, price tables, schedules, bookings, inventory, KPI sheets. Parses sheets into structured, typed rows on the design machine with a bundled zero-dependency script, shapes them, and imports as Data entries, Property Bank values, or data-calculation sources; large tables can also feed the vectorStore for semantic search. Covers re-import when the sheet changes and runtime ingestion for apps that accept uploaded sheets. Triggers on "import this Excel", "use this spreadsheet", "load the price list", or a spreadsheet path in the prompt. Do NOT use to create or edit spreadsheet files as the deliverable, and not for PDFs, Word docs, or slide decks (use the pdf / docx / pptx skills).4license: MIT5---67# Spreadsheet Import89Turn a spreadsheet into live app data: Data entries, Property Bank values, or10data-calculation sources.1112**Announce at start:** "I'm using the xlsx skill to import this spreadsheet."1314## Step 1: Inspect1516Run the bundled parser in listing mode to see sheets, sizes, and a first-row17preview. Resolve the script path against this skill directory (the directory18containing this SKILL.md) and pass the absolute path to `bun` as a single19command — no pipes, redirections, or chained shell commands. The script has20zero dependencies and runs fully offline.2122```bash23bun /absolute/path/to/xlsx/scripts/xlsx_to_json.ts --list path/to/file.xlsx24```2526Confirm with the user which sheet and columns matter when there is more than27one plausible target. Watch for: header rows that don't start at row 1, merged28cells, unit rows under headers, and trailing summary rows.2930## Step 2: Parse to structured rows3132```bash33bun /absolute/path/to/xlsx/scripts/xlsx_to_json.ts --sheet "Menu" --header-row 2 --out output/import/menu.json path/to/file.xlsx34```3536The output is `{ source, sheet, headerRow, columns, rowCount, rows }` with37typed cells. Rules the script applies:3839- **Dates:** spreadsheet serial numbers become ISO strings (`--dates serial`40 keeps raw numbers). Verify one sample date against the source before41 importing — date detection is heuristic.42- **Formulas:** the last **computed value** is exported, never the formula.43- **Empty cells** become `null`, not `""`.44- **Merged cells:** the value lands in the top-left cell; add `--fill-merged`45 to copy it across the merged range.46- CSV/TSV files parse directly; strings with leading zeros stay strings.4748For very large sheets, parse is capped at 5000 rows by default — confirm the49shape on the first rows, then re-run with `--limit 0` for everything.5051## Step 3: Choose the destination5253| Content | Destination | Why |54|---|---|---|55| Values edited rarely, used in one place (title, phone, prices on one board) | Brick properties / Property Bank values | simplest; no indirection |56| Lists and tables the UI iterates (menu items, rooms, products) | **Data entries** (project Data, edited with `edit_entry`) | structured; drives list UIs |57| Content users will search or ask questions about | vectorStore ingestion (see `ai-recipes` doc-qa pattern) | semantic search / RAG |58| Data that must update on devices without redeploy | Data Bank (cloud data via the dataBank generator) | live updates to the fleet |5960Default for tabular data: Data entries. Ask the user only when the destination61changes the app's structure.6263## Step 4: Import6465- Data entries: use the `edit_entry` tool (Data type). Derive stable keys from66 a natural column (SKU, item name) — not from row order — so re-imports67 update instead of duplicate.68- Shape rows to what the UI needs before importing: rename columns to69 property names (the script's `columns[].key` mapping is the starting70 point), coerce types, drop unused columns.71- Keep the parsed JSON in `output/import/` — it records the source file,72 sheet, header row, and column mapping, which makes the import reviewable73 and repeatable.7475## Step 5: Verify7677Preview in the simulator: the list UI renders every row; spot-check first,78last, and one middle row against the source file. Check type-sensitive79displays: dates, currency, decimals, phone numbers.8081## Re-import (the sheet changed)82831. Re-run Step 2 with the same flags (they are recorded in the previous JSON).842. Diff old vs new JSON; report added/removed/changed keys to the user.853. Update Data entries by stable key; never wholesale-delete unless asked.8687## Runtime ingestion (apps that accept sheets while running)8889For apps that must ingest user-uploaded files at runtime, don't parse at90design time — wire the app itself:9192- The `vectorStore` generator's insert-file command ingests Office/OpenOffice93 documents into searchable chunks (works on all launchers).94- Data calculations can call `parseDocument(path)` for text extraction.9596Both give **text**, not structured cells — for structured runtime data,97prefer the Data Bank flow (update data in the cloud, devices subscribe via the98dataBank generator) over runtime file parsing.99100## Guidelines101102- Sample before bulk: for files with thousands of rows, parse 20 rows first103 (`--limit 20`), confirm the shape with the user, then run the full import.104- Numbers displayed as text (leading zeros, phone numbers) must stay strings —105 respect the source column formatting.106- Multi-sheet workbooks: one logical table per destination; don't merge107 unrelated sheets into one Data list.108109## When Not To Use110111- The deliverable is a spreadsheet file (creating/editing .xlsx) — out of scope.112- The file is a PDF, Word document, or slide deck — use the `pdf` / `docx` /113 `pptx` skills.114- Tiny one-off values (a single number) — just set the property directly.
mybigday