XLSX

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