---
name: sheet
description: 'Inspect, summarize, and convert spreadsheet workbooks (Excel XLSX, ODS). Tools: convert, inspect. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: documents, engineering
  tools: convert.py, inspect.py
---

# Sheet

Inspect, summarize, and convert spreadsheet workbooks (Excel XLSX, ODS).

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/convert.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `convert.py`

Convert a sheet from an Excel (XLSX) or ODS spreadsheet into clean CSV, TSV, or JSON.

Use when the user wants to extract data from an Excel or ODS workbook into a flat format (CSV, TSV, JSON) or save a sheet as a table.

```sh
<skill-dir>/convert.py -p workbook="<workbook>" [-p sheet=1] [-p format=csv] --output sheet.csv
```

Parameters:
- `workbook` (file, required) — Spreadsheet workbook mounted at /input/workbook
- `sheet` (string, optional, default `1`) — 1-indexed sheet index or sheet name to convert (defaults to the first sheet)
- `format` (string, optional, default `csv`) — Output format: csv, tsv, json

Outputs:
- `sheet.csv` — copy out with `--output sheet.csv[=<host path>]`
- `sheet.tsv` — copy out with `--output sheet.tsv[=<host path>]`
- `sheet.json` — copy out with `--output sheet.json[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `inspect.py`

Inspect spreadsheet workbooks (XLSX, ODS), listing sheet names, row and column dimensions, and header columns.

Use when the user wants to see the structure, sheets, dimensions, or column names of an Excel or ODS spreadsheet without reading all rows.

```sh
<skill-dir>/inspect.py -p workbook="<workbook>" [-p format=markdown]
```

Parameters:
- `workbook` (file, required) — Spreadsheet workbook mounted at /input/workbook
- `format` (string, optional, default `markdown`) — Output format: markdown or json

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.
