excel-tools

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

1. Run excel-tools sheets <file> for multi-sheet files.
2. Run excel-tools preview <file> --sheet <name> --format md to inspect shape and sample data.
3. Use excel-tools read --range --format json for targeted retrieval when exact parsing matters.
4. For updates, write patch values to a small CSV file and call excel-tools update with --output.
5. 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.