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
    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

```bash
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

```js
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

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

### With JSON data

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

### With formulas

```bash
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 whether the first row is a header, writes a styled workbook, and gives you a clean `.xlsx` starting point.

## Recalculation And Templates

- Use `skills/xlsx/scripts/recalc.cjs` after significant formula edits when `soffice` is available to refresh calculated values through LibreOffice.
- Prefer user-provided templates from the current workspace when the user needs a financial model or branded workbook preserved.
- If `recalc.cjs` cannot run because `soffice` is unavailable, keep formulas intact, do not guess cached values, and state the verification limitation plainly.
- For finance-specific presentation rules, source notes, and number formats, load [references/financial-modeling.md](references/financial-modeling.md).