Spreadsheet

Spreadsheet Skill

Create, read, pivot, chart-annotate, and validate Excel XLSX files using Node.js.

Routes

Decision Rules

1. Create vs Read: If the file does not exist yet, use spreadsheet.create. If it exists, use spreadsheet.read or spreadsheet.validate.
2. Pivot: Use when you need to aggregate numeric data by row/column groupings. Specify at least one row key, one column key, and one value with aggregation.
3. Chart: Note that exceljs cannot embed native Excel charts. spreadsheet.chart writes metadata to a ChartConfig sheet. Use this when you need to document chart intent; tell the user they need Excel/LibreOffice to render it.
4. Validate: Use before processing a user-supplied XLSX to detect errors. Always check data.valid in the result.

Path Constraints

All write operations (create, pivot) require outputPath to be under:

• /tmp/ — for ephemeral files
• <project-root>/data/spreadsheets/ — for persistent files

Examples

Create a sales workbook

{
  "tool": "spreadsheet.create",
  "params": {
    "outputPath": "/tmp/sales-2026.xlsx",
    "sheets": [{
      "name": "Q1",
      "columns": [
        {"header": "Region", "key": "region", "width": 20},
        {"header": "Revenue", "key": "revenue", "width": 15},
        {"header": "Units", "key": "units", "width": 10}
      ],
      "rows": [
        {"region": "North", "revenue": 50000, "units": 120},
        {"region": "South", "revenue": 38000, "units": 95}
      ]
    }]
  }
}

Read an XLSX

{
  "tool": "spreadsheet.read",
  "params": {
    "path": "/tmp/sales-2026.xlsx",
    "sheet": "Q1"
  }
}

Build a pivot table

{
  "tool": "spreadsheet.pivot",
  "params": {
    "inputPath": "/tmp/sales-2026.xlsx",
    "outputPath": "/tmp/pivot-2026.xlsx",
    "sourceSheet": "Q1",
    "rows": ["region"],
    "columns": [],
    "values": [{"col": "revenue", "agg": "sum"}, {"col": "units", "agg": "count"}]
  }
}

Validate a workbook

{
  "tool": "spreadsheet.validate",
  "params": {"path": "/tmp/sales-2026.xlsx"}
}

Error Handling

Limitation

spreadsheet.chart writes metadata only — exceljs has no native chart API. To render the chart, open the file in Excel or LibreOffice and use the ChartConfig sheet values to create the chart manually.