/xlsx

name: xlsx
description: Create, edit, inspect, and analyze `.xlsx` spreadsheets and Excel workbooks. Use this skill whenever the user asks to make a spreadsheet, generate an Excel file, create a table as xlsx, import CSV/TSV to xlsx, or work with any `.xlsx` file.
user-invocable: true
disable-model-invocation: false
requires:
  bins:
    - node
  node_modules:
    - xlsx
    - xlsx-populate
    - csv-parse
    - iconv-lite
metadata:
  hybridclaw:
    category: office
    install:
      - id: node-libs
        kind: runtime-tools
        label: Install the office Node libraries for host-sandbox agents
    short_description: "Create and edit Excel spreadsheets (.xlsx)."
    tags:
      - office
      - spreadsheet
      - xlsx
      - excel
      - table
      - csv
    related_skills:
      - docx

XLSX

Use this skill whenever the user asks to create, inspect, analyze, or edit an `.xlsx` workbook, or to turn delimited tabular data into a polished `.xlsx` file.

Default Workflow

1. For creation tasks, use `skills/xlsx/scripts/create_xlsx.cjs` to create a new workbook from headers/rows or JSON data. Fall back to a workspace `.cjs` script only when the bundled script cannot handle the requirement. 2. Use `skills/xlsx/scripts/import_delimited.cjs` for messy CSV or TSV inputs when it saves time, then polish the workbook with `xlsx-populate`. 3. Do table reshaping in plain JavaScript, then write the final workbook with `xlsx-populate`. 4. After meaningful formula edits, run LibreOffice-backed recalculation when `soffice` is available so cached values and error checks are current. 5. Save the finished workbook inside the workspace and return the `.xlsx` artifact.

Rules

• Keep formulas as formulas. Do not replace derived cells with hardcoded values unless the user explicitly asks for static outputs.
• Keep formulas dynamic. Put user-editable assumptions and drivers in dedicated cells or sheets instead of burying hardcoded constants inside long formulas.
• `xlsx-populate` does not recalculate formulas. Keep formula strings intact and use LibreOffice-backed verification when cached values matter and the runtime says `soffice` is available.
• After significant formula edits, run `node skills/xlsx/scripts/recalc.cjs workbook.xlsx --json` when `soffice` is available and fix any `#REF!`, `#DIV/0!`, `#VALUE!`, `#N/A`, or `#NAME?` errors before delivery.
• Match existing workbook conventions exactly when editing templates or established models. Existing fonts, fills, borders, number formats, freeze panes, filters, named ranges, and color conventions override generic style rules.
• For new user-facing workbooks without a template, use consistent professional styling: one readable font, explicit header styling, sensible widths, and alignment or freeze panes where they help readability.
• Preserve existing worksheets, named ranges, freeze panes, filters, and formats unless the user asked for a redesign.
• Prefer `.xlsx` as the final deliverable. Only fall back to CSV/TSV if the user explicitly wants a flat export.
• Use number formats, explicit column widths, alignment, and header styling for user-facing workbooks.
• For creation tasks ("make a spreadsheet", "create an xlsx"), always use `skills/xlsx/scripts/create_xlsx.cjs` first. Only write a custom workspace script if the user's requirements exceed what the bundled script supports.
• Treat `skills/` as bundled tooling. Do not write generated task scripts under `skills/xlsx/` or `skills/office/` for normal workbook jobs.
• Put new helper scripts in workspace `scripts/` or the workspace root, then run them from there. Use `skills/xlsx/scripts/...` and `skills/office/...` only as shipped helper commands.

Variant Guidance

• For financial models or other heavily formatted analytical workbooks, read [references/financial-modeling.md](references/financial-modeling.md) before applying conventions.

Useful Commands

node skills/xlsx/scripts/create_xlsx.cjs output.xlsx --headers "Name,Age,City" --rows "Alice,30,NYC;Bob,25,LA" --json
node skills/xlsx/scripts/recalc.cjs workbook.xlsx --json
node skills/xlsx/scripts/import_delimited.cjs raw.csv cleaned.xlsx --json

Starter Pattern

const XlsxPopulate = require("xlsx-populate");

async function main() {
  const workbook = await XlsxPopulate.fromBlankAsync();
  const sheet = workbook.sheet(0).name("Summary");

  sheet.cell("A1").value("Revenue");
  sheet.cell("B1").value("Cost");
  sheet.cell("C1").value("Profit");
  sheet.cell("A2").value(120000);
  sheet.cell("B2").value(45000);
  sheet.cell("C2").formula("A2-B2");

  sheet.range("A1:C1").style({
    bold: true,
    horizontalAlignment: "center",
    fill: "D9EAF7"
  });

  sheet.freezePanes("A2");
  sheet.column("A").width(16);
  sheet.column("B").width(16);
  sheet.column("C").width(16);

  await workbook.toFileAsync("profit-summary.xlsx");
}

main();

Create a New Workbook

Use `skills/xlsx/scripts/create_xlsx.cjs` to create a professionally styled `.xlsx` from scratch. This is the preferred method for creation tasks.

With headers and rows

node skills/xlsx/scripts/create_xlsx.cjs output.xlsx --headers "Name,Age,City" --rows "Alice,30,NYC;Bob,25,LA" --json

With JSON data

node skills/xlsx/scripts/create_xlsx.cjs output.xlsx --json-data '[{"Name":"Alice","Age":30},{"Name":"Bob","Age":25}]' --json

With formulas

node skills/xlsx/scripts/create_xlsx.cjs output.xlsx --headers "Revenue,Cost,Profit" --rows "120000,45000,=A2-B2" --sheet-name "Summary" --json

The script applies professional styling automatically: bold headers with fill color, freeze panes at row 2, auto-filter, and auto-sized column widths. Numbers are auto-detected and written as numbers, not strings. Values starting with `=` are written as formulas.

CSV / TSV Import

• Use `skills/xlsx/scripts/import_delimited.cjs` for messy CSV or TSV inputs.
• It auto-detects encoding and delimiter, infers wh