name	excel-tools
description	Use when: inspecting, previewing, reading, or updating spreadsheet files with the excel-tools CLI; handling CSV, TSV, XLSX, XLS, XLSM, or ODS files safely from an agent workflow.

excel-tools CLI Skill

Use excel-tools when an agent needs to inspect or edit spreadsheet data without dumping an entire workbook into context.

Safety first

Before relying on Excel data, prefer excel-tools preview or excel-tools sheets instead of opening the full file. The tool rejects complex XLSX files that contain charts, drawings, media, embedded objects, ActiveX controls, or VML drawings.

If the tool rejects a file, do not bypass the guard. Ask the user whether they want manual handling or a different tool.

Common commands

Preview a file:

excel-tools preview data.xlsx

Preview a specific sheet:

excel-tools preview data.xlsx --sheet Sheet1

Preview in Markdown for LLM-friendly reading:

excel-tools preview data.xlsx --sheet Sheet1 --format md

Preview in JSON for precise agent parsing:

excel-tools preview data.xlsx --sheet Sheet1 --format json

Limit preview size:

excel-tools preview data.csv --rows 5 --cols 8

Limit cell display width for table or Markdown output:

excel-tools preview data.csv --format md --max-cell-width 32

List sheets:

excel-tools sheets data.xlsx

Read a range:

excel-tools read data.xlsx --sheet Sheet1 --range A1:D20

Read a range as JSON:

excel-tools read data.xlsx --sheet Sheet1 --range A1:D20 --format json

Read selected rows or columns:

excel-tools read data.csv --rows 1,3,5
excel-tools read data.csv --cols A,C,F

Update a range into a new output file:

excel-tools update data.xlsx --sheet Sheet1 --range B2:C3 --values patch.csv --output data.updated.xlsx

Agent workflow

Run excel-tools sheets <file> for multi-sheet files.
Run excel-tools preview <file> --sheet <name> --format md to inspect shape and sample data.
Use excel-tools read --range --format json for targeted retrieval when exact parsing matters.
For updates, write patch values to a small CSV file and call excel-tools update with --output.
Re-run preview or read --range against the output file to verify the change.

Output expectations

Preview/read output includes:

current sheet name
total rows for the current sheet
total columns for the current sheet
number of sheets
terminal-rendered table
sheet list at the bottom
row numbers in rendered rows
merged cell metadata when the selected range intersects merged cells

Default preview size is 10 rows by 20 columns.

Supported output formats:

--format table: terminal table for humans; includes row numbers and wraps long cells by --max-cell-width.
--format md: Markdown table for LLM-readable compact output; includes row numbers, uses <br> for wrapped cells, and appends Merged cells: ... when needed.
--format json: structured output for agents; preserves raw cell values and includes row numbers plus merged_cells metadata.

Merged cell handling:

Cell data remains rectangular: the merged region's upper-left value appears in the upper-left cell, and other cells in the region remain empty.
json is preferred when merged-cell semantics matter because it includes exact merged ranges.
table and md list merged ranges after the table; they do not attempt real rowspan/colspan rendering.

Do not use for

Extracting charts or images.
Preserving rich Excel formatting.
Editing files with macros or embedded objects.
Full workbook dumps.

name	excel-tools
description	Use when: inspecting, previewing, reading, or updating spreadsheet files with the excel-tools CLI; handling CSV, TSV, XLSX, XLS, XLSM, or ODS files safely from an agent workflow.