Spreadsheets skill
This skill includes guidelines for how to produce a correct, polished spreadsheet artifact quickly that completes the user's request. When producing spreadsheets or workbooks, you will be judged on layout, readability, style, adherence to industry norms/conventions and correctness. Follow the guidelines below for how to use the APIs effectively and how to verify your output before finalizing work for the user.
For complex, analytical, financial or research involved tasks, you are especially judged on correctness and quality. You need to be professional. For these, always make sure you have a plan for how you're organizing the spreadsheet, and the data or visualizations within each sheet. For business, finance, operations, dashboard, and data-analysis prompts, aim for an output that can compete with a strong analyst-built workbook, not just a functional grid. A good default shape is an executive summary or dashboard first, then source/assumptions, then model/detail sheets. For simpler tasks like a creating template or tracker, or things that do not require research, prioritize doing the spreadsheet build and edits quickly, while ensuring the user's request is fulfilled.
For additional stylistic best practices, follow: style_guidelines.md
Tools + Contract
- Use the existing installed
@oai/artifact-tool JS package which exists in the default Codex workspace dependencies node_modules for authoring, editing, inspecting, rendering, and exporting spreadsheet .xlsx workbooks. Use the bundled workspace Node.js and Python runtimes for local builders and helper scripts.
- Run builder files from a writable conversation-specific temp or workspace directory, not from the managed dependency directory.
- For JavaScript builders, do not use
NODE_PATH; ensure bundled packages resolve through normal Node package lookup from the builder file.
- If needed, create a local
node_modules directory link or Windows junction to the bundled node_modules; do not copy bundled dependency directories or import internal package files directly.
- Prefer to use a single executable JavaScript builder (.mjs); patch and rerun the same builder file when iterating. Do not put script bodies in shell heredocs or inline shell script bodies, or keep extra workspace-local builder copies.
- Final user-facing response: Must include a short summary of the workbook/sheets/ranges created or edited, plus standalone Markdown link(s) only to final
.xlsx artifact(s), with this link format [Revenue Model - model.xlsx](/absolute/path/to/model.xlsx); using a platform-appropriate absolute filesystem path. If there are multiple requested final workbooks, put each final .xlsx Markdown link on its own line. Do not wrap final artifact links in backticks or code fences, and do not put them in bullets, headings, or prose sentences.
- The final response summary must describe only the user-visible result. Do not mention implementation details such as
artifact_tool, artifact-tool, @oai/artifact-tool, the Node/JS builder, copied builder scripts, package manifests, export workflow, verification workflow, rendered previews, or internal tooling unless explicitly requested.
- Do not link to or mention rendered previews, copied builder scripts, intermediate JSON/CSV/log files, scratch files, or other support artifacts unless explicitly requested. Do not delete or suppress support files just to satisfy this response rule.
- Do not use alternate workbook creation/editing libraries such as
openpyxl, xlsxwriter, or pandas.ExcelWriter unless the user explicitly asks for a non-artifact-tool fallback.
- For analysis outside workbook authoring, use the simplest reliable installed tool. If analysis cannot be done directly in the JavaScript script or via formulas in the spreadsheet, additional Python libraries such as
pandas/numpy are available in the bundled Python runtime in the default Codex workspace dependencies. Save analysis outputs as JSON/CSV; the JavaScript builder should read those files and create the workbook with @oai/artifact-tool. Keep workbook-derived or user-editable calculations as spreadsheet formulas when auditability or future editing matters.
- Use the update_plan tool to communicate your approach with the user and ensure you're staying on track to produce the best outcome for the user. Generally, your plan should emphasize speed to a correct first version, followed by incremental improvements and verification. Incrementally rendering your work and assessing overall aesthetics, formatting and correctness along the way is very important (you should rigorously inspect the output and be confident in quality), but do not get stuck in a long render-verify loop. As part of your plan, think about the best practices and conventions to follow for the specific type of spreadsheet you're creating and the best way to structure the workbook for readability and usability.
General Rules
- Start meaningful edits quickly; avoid long upfront API exploration.
- Core APIs are listed in the API reference section below. Use them.
- If these skill instructions are already loaded in context, do not spend a shell turn re-reading this
SKILL.md from disk. Move directly to the prompt, attachments, and workbook build.
- For workbook with multiple tabs/sheets, create/populate non-formula inputs/tables and sheets prior to populating cross-sheet formulas.
Approach for quickly building a new spreadsheet
- Setup: import
@oai/artifact-tool, create workbook/sheets for new files.
- Build quickly: bulk-write headers/data/formulas; then formatting/validation/conditional formatting; add charts/tables only when needed.
- Use additional focused calls if helpful for streamed progress.
- Near completion: inspect key ranges, scan formula errors, render all the sheets and verify, run a validation pass
- Export
.xlsx
Making edits on a spreadsheet
If a user asks to edit or add to an existing spreadsheet:
- For visual fix requests, start with the smallest plausible local change rather than applying sheet-wide autofit, wrapping, or restyling.
- When making edits, ensure existing formulas and patterns are consistent. For example, if asked to add another column or row to a table and there is conditional formatting applied to the whole table, it should extend to the new column or rows as well.
- If specific cells/rows/columns are specified in prompt, limit edits to those ranges unless a broader change is clearly necessary. The exceptions are when other parts of the spreadsheet depend on them, e.g. if there's a dynamic chart that is based on the range of values in a table and a new row is added, the chart should include that new row. Another example is if conditional formatting was already set for a table from A1:C5, and you add a new column D, the conditional formatting should be updated (or deleted and re-created) to cover A1:D5.
- For column resizing, avoid autofitting by default: instead, inspect only relevant data range, measure the longest text entry in that range, and set columnWidthPx to an estimated width based on text length (with a reasonable min/max cap). Use autofit only when the user explicitly asks for it.
Handling queries and questions
- The user may ask questions about the sheet instead of requesting an edit or a change. Simply answer those questions about the spreadsheet based on the context available rather than making an edit the user didn't intend for. You can use inspect to learn more or directly read values/formulas/tables etc via accessor methods.
Error Recovery
On first error:
- Read error text.
- Run one targeted
workbook.help("<exact_api>") query only if needed.
- Retry with minimal patch (not full rewrite).
- Continue from existing workbook state.
Do not loop indefinitely on similar failures.
Quality Guidelines
- Keep layout readable and bounded, contents visible:
- avoid extreme width/height from unconstrained autofit
- cap oversized widths/heights after
autofit + wrap_text
- Prefer formula-driven logic over manual painted cells when logic is expected.
- Derived values must be formulas (not hardcoded) and legible.
- Use absolute/relative references correctly for fill/copy behavior.
- Do not use magic numbers in formulas; reference cells (e.g.
=H6*(1+$B$3)).
- Blank editable templates must look blank/neutral before user data is entered. Count, ranking, best/worst, IRR/RATE/XIRR, variance, and status formulas should guard on required input cells and return
"", 0, or a clear "No entries yet" state as appropriate. Alternatively, prefill with a few rows of example data.
- Include at least one visual summary for tracker/planning requests when appropriate (KPI block, chart, dashboard area).
- For dashboard, visualization, chart-ready analysis, budget/reporting, trend, schedule/timeline, and KPI prompts with plottable data, include at least one native Excel chart unless a verified export failure remains after simplifying the chart. Do not silently replace all charts with styled tables.
- For presentation-ready analytical workbooks, plain range formatting alone is usually not enough. Prefer real Excel structures where useful: tables, freeze panes, filters, data validation, conditional formats, and at least one chart/KPI/dashboard visual when the prompt implies summary analysis.
- In rendered previews of dashboards and summary sheets, check financial values and row labels at normal zoom. Widen columns, adjust row heights, or move chart panels until important numbers and text are not clipped, awkwardly wrapped, or hidden.
Completion Criteria
Complete only when:
- Workbook content is populated and formulas compute.
- No obvious formula errors in key scanned ranges (no bad refs/off-by-one/circular errors).
.xlsx saved to outputs/<unique_thread_id>/.
- Layout is organized, legible, and aligned to request style (or default formatting baseline).
Verification Rules
Before final response, verify values/formulas and visual quality.
- Inspect key ranges:
const check = await workbook.inspect({
kind: "table",
range: "Dashboard!A1:H20",
include: "values,formulas",
tableMaxRows: 20,
tableMaxCols: 12,
});
console.log(check.ndjson);
Inspect targeting:
- Prefer sheet-qualified ranges (
"Sheet!A1:H20") or sheetId.
- Scan formula errors:
const errors = await workbook.inspect({
kind: "match",
searchTerm: "#REF!|#DIV/0!|#VALUE!|#NAME\\?|#N/A",
options: { useRegex: true, maxResults: 300 },
summary: "final formula error scan",
});
console.log(errors.ndjson);
- Render sheets/ranges to verify visual output (skip if already verified and no style changes):
const blob = await workbook.render({ sheetName: "Sheet1", range: "A1:H20", scale: 2 });
Make sure you do at least one visual pass of all the sheets in the workbook before the final export.
Visual requirements:
- Fix severe defects before finalizing: blank/broken charts, clipped key headers or numbers, unreadable colors, obvious formula errors, default blank sheets, or content outside the visible working area.
- Ensure logical labels or titles appear once, texts are all clearly visible, and merged ranges exist where labels or content intentionally span multiple columns.
- Do one focused visual repair pass after the initial render. Do not spend additional passes on minor polish once the workbook is correct, legible, and exported; note any minor limitation briefly and finalize.
- Keep verification compact:
- Inspect key ranges.
- Avoid huge NDJSON dumps.
- Export:
await fs.mkdir(outputDir, { recursive: true });
const output = await SpreadsheetFile.exportXlsx(workbook);
await output.save(`${outputDir}/output.xlsx`);
- Finalize immediately after successful export + compact verification.
- Do not export extra
.xlsx variants unless asked.
- Do not keep iterating on alternate designs once requirements are met, unless asked.
Additional Instructions
Read the following templates instructions ONLY when a request relates to any of the following:
- Investment banking, company financial models, valuation, multi-statement forecasts, or source-backed financial filing analysis: templates/financial_models.md
Do not load these for other tasks that are unrelated unless the prompt explicitly asks for it.
Source and PDF Extraction
- For PDF or 10-K/10-Q style inputs, can read PDF via python library
pypdf, if available, then use one small structured extraction script to collect all required facts into a dict/JSON object. Avoid many ad hoc rg/sed passes over the same text.
- Keep source notes compact: record file name, section/table label, and enough context to audit the number. Do not paste large PDF excerpts into the workbook unless requested.
Using artifact_tool APIs (JavaScript)
Required Imports + Startup
Import existing workbook only when needed:
import { FileBlob, SpreadsheetFile } from "@oai/artifact-tool";
const input = await FileBlob.load("path/to/input.xlsx");
const workbook = await SpreadsheetFile.importXlsx(input);
Import CSV text directly when the source or intermediate data is CSV:
import fs from "node:fs/promises";
import { Workbook } from "@oai/artifact-tool";
const csvText = await fs.readFile("path/to/input.csv", "utf8");
const workbook = await Workbook.fromCSV(csvText, { sheetName: "Sheet1" });
Prefer Workbook.fromCSV(...) over hand-parsing CSV rows; clean or analyze CSV with Python/Node first only when needed.
Create new workbook:
import fs from "node:fs/promises";
import { SpreadsheetFile, Workbook } from "@oai/artifact-tool";
const workbook = Workbook.create();
const sheet = workbook.worksheets.add("Inputs");
Final export:
await fs.mkdir(outputDir, { recursive: true });
const output = await SpreadsheetFile.exportXlsx(workbook);
await output.save(`${outputDir}/output.xlsx`);
Build Rules
- Prefer block writes (
range.values, range.formulas) over per-cell loops. Matrix shape must match the target range (for example "D4:M4" should be a 1x10 matrix, row x col).
- Seed scalar formulas once, then
fillDown() / fillRight(). For dynamic-array formulas (SEQUENCE, UNIQUE, FILTER, SORT, VSTACK, HSTACK), write only the anchor cell and let the result spill after.
- Use
range.displayFormulas plus range.formulaInfos when you need to understand a spill child or a data-table output cell.
- You do not need to call recalculate; calculation automatically happens.
- Date handling:
- Prefer real
Date objects for sortable/charted/formula date columns.
- Apply date formats explicitly (for example
yyyy-mm-dd).
- Use JSON-serializable values for non-Date cells:
string | number | boolean | null.
- If a cell is intended to display literal text that begins with
=, write it as a value prefixed with a single quote (for example '=B2*C2). This includes formula descriptions, validation examples, and labels; do not write these cells through range.formulas.
- Create every worksheet referenced by formulas before writing any cross-sheet formulas.
- When rebuilding dashboards, delete drawings first with
sheet.deleteAllDrawings(). range.clear() does not remove charts, shapes, or images.
- Verify with
await workbook.inspect(...); use workbook.help(...) only when the quick surface below is insufficient.
Conventions
- Use camelCase API names and option keys.
- Cell/range addressing: A1 notation (
sheet.getRange("A1:C10")).
- Drawing anchors (
sheet.charts, sheet.shapes, sheet.images): 0-based { row, col }.
- Drawing offsets/extents use pixels (
rowOffsetPx, colOffsetPx, widthPx, heightPx).
Discovery Policy (Strict)
- Use this quick API surface first.
- Use
workbook.help(...) only when blocked by uncertainty.
- For help queries, start with exact feature/path lookups (
chart, worksheet.getRange, worksheet.freezePanes, range.dataValidation, chart.series.add). If an exact path fails, one broader wildcard search is allowed.
- Do not repeat semantically similar help queries.
- If one help query returns 0 matches, reformulate once, then proceed best-effort.
render can be used to examine an existing workbook visually and for visual verifications.
Useful help calls:
console.log(workbook.help("shape.add", { include: "examples,notes" }).ndjson);
console.log(
workbook.help("*", {
search: "fill|borders|autofit",
include: "index,examples,notes",
maxChars: 6000,
}).ndjson,
);
Reading existing/imported workbooks
- On existing/imported workbooks, get a compact summary via
inspect to understand what already exists and where.
- Prefer
inspect(...) for workbook understanding and discovery across broad areas.
- Prefer direct getters like
range.formulas when you already know the target range and need the exact rectangular formula matrix.
- If formula locations are unknown, prefer
inspect({ kind: "formula", ... }) over reading range.formulas across a very large area.
- Prefer to set
maxChars, tableMaxRows, tableMaxCols, and/or maxResults to prevent large dumps of data.
Inspect for workbook understanding
await wb.inspect({
kind: "workbook,sheet,table",
maxChars: 6000,
tableMaxRows: 6,
tableMaxCols: 6,
tableMaxCellChars: 80,
});
- Quick overview of sheet ids and names:
await wb.inspect({ kind: "sheet", include: "id,name" })
- Formula discovery in a targeted area:
await wb.inspect({ kind: "formula", sheetId: firstSheetName, range: "A1:Z30", maxChars: 2500, options: {maxResults:50} })
- Checking existing styles in a targeted area:
await wb.inspect({ kind: "computedStyle", sheetId: firstSheetName, range: "A1:E10", maxChars: 2500 })
- Common
kind tokens: workbook, sheet, table, region, match, formula, thread, computedStyle, definedName, drawing
- Inspects can also be used to zoom in on specific areas, especially for target edits:
await wb.inspect({
kind: "region",
sheetId: firstSheetName,
range: "A1:Z30",
maxChars: 2500,
});
- Inspect output may include JSON records with
"id" values (for example "ws/r5qsk5"), which you can resolve back to workbook objects with wb.resolve(...):
wb.resolve("ws/...") -> worksheet
wb.resolve("th/...") -> comment thread
Additional feature-specific notes
Merging cells
- Merging cells is useful for headers, dashboards, visual descriptors, and other multi-cell labels.
- If you plan to set a range of cells to a single value, consider merging those cells first.
For example:
const range = sheet.getRange("I23:N24");
range.merge();
range.values = [["Some long description that should cross multiple cells"]];
Known Gotchas (Do Not Repeat)
- Do not set undocumented attributes on remote objects.
Workbook.create() starts with no sheets; add one before calling getActiveWorksheet().
- Use matrix sizes that match target ranges unless you intentionally spill.
- If a formula appears unsupported, use an alternate equivalent.
- For cross-sheet formulas in a newly created workbook, create all referenced worksheets first, then write formulas. Avoid writing formulas that reference sheets that have not been added yet.
- Avoid full-column formula references such as
A:A, $A:$A, or Sheet!B:B. Prefer bounded ranges sized to the editable table, e.g. $A$6:$A$205, especially inside COUNTIFS, SUMIFS, INDEX, and lookup formulas.
- If export fails, isolate the cause by checkpoint-exporting after each major feature block: base sheets, values/formulas, formatting, conditional formatting, tables, charts/rendering. Do this before rewriting the workbook.
- If export fails with
invalid int32: NaN or another serialization error after formatting or charts, do not rerun the same script unchanged. First remove or simplify optional drawing/chart/style details in this order: nested/custom border configs, custom chart axis/style mutations, broad row/column formatting/autofit calls, then nonessential drawings. Preserve values/formulas and keep or retry a minimal helper-range chart when the prompt needs charts; only drop all charts/drawings if the simplified chart still prevents export.
- Prefer fills, font hierarchy, spacing, and section bands over complex nested border objects. If you use borders, start with a minimal preset or a very simple thin/light border on a bounded range and checkpoint export before applying borders widely. Avoid nested
inside/around/outline border configs and border weight settings unless you have already checkpoint-exported that exact pattern successfully.
- For chart-heavy dashboards, checkpoint export after the first basic helper-range chart before adding multiple charts or optional axis/formatting mutations. If a chart export failure happens twice, keep the cleanest minimal chart that exports or replace the failing chart with a clearly labeled helper table/KPI block rather than spending the task on repeated chart debugging.
- Keep formatting and formulas on bounded ranges. Avoid whole-row or whole-column formatting/autofit for generated workbooks unless you have verified the export immediately afterward.
Quick API Surface (High-Value + Common)
Core workbook/file APIs
import { FileBlob, SpreadsheetFile, Workbook } from "@oai/artifact-tool"
const workbook = Workbook.create(); const sheet = workbook.worksheets.add("Sheet1")
const workbook = await SpreadsheetFile.importXlsx(arrayBufferOrFileBlob)
const xlsx = await SpreadsheetFile.exportXlsx(workbook); await xlsx.save("output.xlsx")
const inspect = await workbook.inspect({ kind: "sheet", include: "id,name", sheetId, range: "A1:C10" })
const help = workbook.help("worksheet.getRange", { include: "index,examples" })
- Preferred:
const blob = await workbook.render({ sheetName: "Sheet1", autoCrop: "all", scale: 1, format: "png" })
- To get the bytes and/or save the blob to file:
const previewBytes = new Uint8Array(await preview.arrayBuffer());
await fs.writeFile(`${outputDir}/preview.png`, previewBytes);
const workbook = await Workbook.fromCSV(csvText, { sheetName: "Sheet1" })
await workbook.fromCSV(csvText, { sheetName: "ImportedData" })
Worksheet selection/creation
workbook.worksheets.add(name)
workbook.worksheets.getItem(name)
workbook.worksheets.getOrAdd(name, { renameFirstIfOnlyNewSpreadsheet: true })
workbook.worksheets.getItemAt(index)
workbook.worksheets.getActiveWorksheet() (only after at least one sheet exists)
Worksheet operations
sheet.getRange("A1:C10"), sheet.getRangeByIndexes(startRow, startCol, rowCount, colCount), sheet.getCell(row, col)
sheet.getUsedRange(valuesOnly?)
sheet.mergeCells("A1:C1"), sheet.unmergeCells("A1:C1")
sheet.freezePanes.freezeRows(1), sheet.freezePanes.freezeColumns(2), sheet.freezePanes.unfreeze()
sheet.tables, sheet.charts, sheet.sparklineGroups (sheet.sparklines alias), sheet.shapes, sheet.images
sheet.showGridLines = false
sheet.dataTables, sheet.conditionalFormattings, sheet.dataValidations
sheet.deleteAllDrawings() removes charts, shapes, and images before a dashboard rebuild.
Range values/formulas
const range = sheet.getRange("A1:C10")
range.values = [[...], ...] (2D matrix of values)
range.formulas = [["=..."], ...]
range.formulasR1C1 = [["=RC[-1]*2"]]
- To read:
range.values / range.formulas / range.displayFormulas / range.formulaInfos (for spill/array formulas)
range.write(matrixOrPayload) (auto-sizes/spills from anchor as needed)
range.writeValues(matrixOrRows)
range.fillDown(), range.fillRight()
sheet.getRange("D2").formulas = [["=..."]]
sheet.getRange("D2:D200").fillDown()
range.clear({ applyTo: "contents" | "formats" | "all" })
range.copyFrom(sourceRange, "values" | "formulas" | "all") source and destination must have the same shape
range.copyTo(destRange, "values" | "formulas" | "all")
range.offset(...), range.resize(...), range.getCurrentRegion(), range.getRow(i), range.getColumn(j)
range.getRangeByIndexes(...), range.getCell(...)
range.merge(), range.merge(true) to merge across, range.unmerge()
Formatting
range.format supports fill, font, numberFormat, borders, alignments, wrapText
range.format.autofitColumns(), range.format.autofitRows()
range.format.columnWidth = 18, range.format.rowHeight = 24
range.format.columnWidthPx = 120, range.format.rowHeightPx = 24
range.setNumberFormat("yyyy-mm-dd")
range.format.numberFormat = [["0"], ["0.00"], ["@"]]
Validation + conditional formatting
range.dataValidation = { rule: { type: "list", formula1: "Categories!$A$2:$A$4" } }
range.dataValidation = { rule: { type: "list", values: ["Not Started", "In Progress"] } }
sheet.dataValidations.add({ range: "B2:B100", rule: { type: "whole", operator: "between", formula1: 1, formula2: 10 } })
range.conditionalFormats.add(type, config)
range.conditionalFormats.addCustom(formula, format)
range.conditionalFormats.addCellIs({...})
range.conditionalFormats.addDataBar({...})
range.conditionalFormats.addColorScale({...})
range.conditionalFormats.deleteAll() / range.conditionalFormats.clear()
sheet.conditionalFormattings.add({ range, rule })
const r = sheet.getRange("B2:B20");
r.conditionalFormats.addCellIs({
operator: "lessThan",
formula: 0,
format: { font: { color: "#DC2626" } },
});
r.conditionalFormats.addCustom("=B2<0", { fill: "#FECACA" });
r.conditionalFormats.addColorScale({
minColor: "#FEE2E2",
midColor: "#FEF3C7",
maxColor: "#DCFCE7",
});
r.conditionalFormats.addDataBar({ color: "accent5", gradient: true });
Tables
- Rules: When adding new tables, set explicit unique names (
TasksTable, SummaryTable).
- You cannot have multiple tables over the same range. Before adding a table on an existing/imported workbook, confirm the target range does not already overlap an existing table. Prefer the initial compact
inspect summary over a separate tables-only scan when available.
const table = sheet.tables.add("A1:H200", true, "TasksTable")
table.rows.add(null, [[...], ...]), table.getDataRows(), table.getHeaderRowRange()
- Read tables:
sheet.tables.items -> Table[]
- Set + Getters:
table.name, table.style, table.style, table.showHeaders
- Toggles for table utilities (set/get):
table.showTotals, table.showBandedColumns = true, table.showFilterButton
table.delete()
Charts
- Rules: When adding or moving charts, do not cover existing data. Put charts in a reserved rectangle with blank gutter columns/rows around the chart area.
- Fast chart path, no help lookup needed for common line/bar/scatter charts: write a compact helper range with text categories and one column per series, then chart that range.
sheet.getRange("F4:H7").values = [
["Month", "Revenue", "EBITDA"],
["Jan", 100, 10],
["Feb", 120, 18],
["Mar", 130, 22],
];
const chart = sheet.charts.add("line", sheet.getRange("F4:H7"));
chart.setPosition("J4", "Q20");
chart.title = "Revenue and EBITDA Trend";
chart.hasLegend = true;
chart.xAxis = { axisType: "textAxis" };
chart.yAxis = { numberFormatCode: "$#,##0" };
- Fast chart path from range:
const chart = sheet.charts.add("line", sourceRange) when the source range already has headers and text x-axis labels.
- Avoid manual
chart.series.add(...) and chart.legend = {...} on the first pass, unless source-range based chart creation does not work (for example, non-continuous data). Use a helper range chart first, then add optional chart styling only if the basic chart renders and exports cleanly.
- If you want to set specific chart props after the helper-range path is not enough:
const chart = sheet.charts.add("bar", chartProps), then checkpoint export before adding optional styling.
- If using compat positioning, always set position:
chart.setPosition("F2", "M20").
sheet.charts.getItemOrNullObject("Chart 1"), sheet.charts.deleteAll()
- To update x/y-axis, prefer compact config assignments such as
chart.xAxis = { axisType: "textAxis", tickLabelInterval: 2 } and chart.yAxis = { numberFormatCode: "$#,##0" }. These help legibility and visibility.
- For month/date x-axes, prefer a chart helper range with text labels such as
Jan 2025 or 2025-01. Do not rely on date axis number formats alone; rendered previews can show Excel serial numbers.
- Chart types:
"bar" | "line" | "area" | "pie" | "doughnut" | "scatter" | "bubble" | "radar" | "stock" | "treemap" | "sunburst" | "histogram" | "boxWhisker" | "waterfall" | "funnel" | "map".
Sparklines
sheet.sparklines.add({...}), sheet.sparklines.clear(), sheet.sparklines.deleteAll() (sheet.sparklineGroups is the worksheet-scoped alias)
Help / Grep
Use workbook.help(...) primarily for obscure/advanced surfaces (for example deep chart axis settings, unusual drawing configs, pivot APIs, or uncommon option schemas).
workbook.help("enum.ShapeGeometry", { include: "index,notes" }).ndjson
workbook.help("enum.*", { search: "ShapeGeometry|LineStyle", include: "index" }).ndjson
workbook.help("shape.add", { include: "examples,notes" }).ndjson
workbook.help("*", { search: "fill|borders|autofit", include: "index,examples,notes", maxChars: 6000 }).ndjson
JavaScript example snippet (runnable)
import fs from "node:fs/promises";
import { SpreadsheetFile, Workbook } from "@oai/artifact-tool";
async function quickApiExample() {
const workbook = Workbook.create();
var sheet = workbook.worksheets.add("ExampleSheet");
sheet = workbook.worksheets.getItem("ExampleSheet");
sheet.getRange("A1:D4").values = [
["Name", "Personality Type", "Age", "Birthday"],
["John Doe", "Introvert", 30, new Date("1990-01-01T00:00:00Z")],
["Jane Smith", "Extrovert", 25, new Date("1995-02-15T00:00:00Z")],
["Jim Very Long Name", "Ambivert", 40, new Date("1980-03-20T00:00:00Z")],
];
sheet.getRange("E1").values = [["Score"]];
sheet.getRange("E2").formulas = [["=C2*10"]]; // score is 10 * age
sheet.getRange("E2:E10").fillDown();
const headerRange = sheet.getRange("A1:E1");
// Styling
const headerFormats = {
fill: "#0F766E",
font: { bold: true, color: "#FFFFFF" },
horizontalAlignment: "center",
verticalAlignment: "center",
rowHeight: 16,
};
headerRange.format = headerFormats;
headerRange.format.autofitColumns();
const dataRange = sheet.getRange("A2:D10");
dataRange.format.wrapText = true;
sheet.showGridLines = false;
// Format dates properly.
sheet.getRange("D2:D10").format.numberFormat = "MM/DD/YYYY";
// Conditional formatting
sheet.getRange("C2:C10").conditionalFormats.addDataBar({
color: "#704023",
gradient: true,
});
sheet.getRange("E2:E10").conditionalFormats.add("cellIs", {
operator: "greaterThan",
formula: 300,
format: { font: { color: "#B91C1C" } },
});
sheet.conditionalFormattings.add({
range: "B2:B10",
rule: {
type: "expression",
formula: '=B2="Introvert"',
format: { fill: "#FCA5A5" },
},
});
// Data validation: Since Personality Type is a dropdown category, add data validation.
sheet.getRange("B2:B10").dataValidation = {
rule: {
type: "list",
values: ["Introvert", "Extrovert", "Ambivert"],
// formula1: "CategoriesSheet!$A$2:$A$4", // Alternative: reference a tunable list
},
};
// Tables: Turn it into a table (for example purposes! Make sure table names are unique)
// NOTE: If hasHeaders=true, the range must include the header row.
const table = sheet.tables.add("A1:E10", true, "PeopleTable");
table.getHeaderRowRange();
// First column is still wide since we only auto-fit the first row. Expand it manually.
sheet.getRange("A1:A10").format.columnWidth = 20;
// Create charts to the right of the table
sheet.getRange("H1:O1").merge();
sheet.getRange("H1").values = [["Charts"]];
sheet.getRange("H1").format = headerFormats;
// Adding charts
const chart = sheet.charts.add("bar", {
from: { row: 1, col: 7 },
extent: { widthPx: 620, heightPx: 320 },
});
chart.title = "Person by Scores";
chart.hasLegend = true;
chart.displayBlanksAs = "zero";
chart.legend.position = "right";
chart.barOptions.direction = "column";
chart.barOptions.grouping = "clustered";
const sheetRef = sheet.name.replaceAll("'", "''");
const dataEndRow = 4; // Keep chart refs to rows with data only.
const scoreSeries = chart.series.add("Scores by Person");
scoreSeries.categoryFormula = `'${sheetRef}'!$A$2:$A$${dataEndRow}`;
scoreSeries.formula = `'${sheetRef}'!$E$2:$E$${dataEndRow}`;
scoreSeries.valuesFormatCode = "0";
chart.setPosition("H2", "O16");
// Granular control over chart axes
chart.xAxis = {
axisType: "textAxis",
title: { text: "Person", textStyle: { fontSize: 13, bold: true } },
position: "bottom",
orientation: "minMax",
textStyle: { fontSize: 10 },
};
chart.yAxis = {
axisType: "textAxis",
title: { text: "Scores", textStyle: { fontSize: 13, bold: true } },
numberFormatCode: "0,000",
numberFormatSourceLinked: false,
};
// Chart 2 - Fastest path with defaults
const chart2 = sheet.charts.add("line", sheet.getRange("B2:C4"));
chart2.title = "Scores by Personality";
chart2.setPosition("H20", "O35");
// Sparklines: add to the right of table
const sparklinesHeader = sheet.getRange("F1");
sparklinesHeader.values = [["Sparklines"]];
sparklinesHeader.format = headerFormats;
sparklinesHeader.format.autofitColumns();
sheet.sparklines.add({
type: "column", // "line" | "column" | "stacked"
sourceData: sheet.getRange("E2:E10"),
targetRange: sheet.getRange("F2:F10"),
seriesColor: "#AAAAAA",
});
// Render
await fs.mkdir("output", { recursive: true });
const pngBlob = await workbook.render({
sheetName: "ExampleSheet",
autoCrop: "all",
scale: 1,
format: "png",
});
const pngBytes = new Uint8Array(await pngBlob.arrayBuffer());
await fs.writeFile("output/example_sheet.png", pngBytes);
console.log("Rendered first sheet to 'output/example_sheet.png'");
// Export
const out = "output/example_sheet.xlsx";
const xlsx = await SpreadsheetFile.exportXlsx(workbook);
await xlsx.save(out);
}
await quickApiExample();
Render:
const imageBlob = await workbook.render({
sheetName: "ExampleSheet",
autoCrop: "all",
scale: 1,
format: "png",
});
Export:
const xlsx = await SpreadsheetFile.exportXlsx(workbook);
await xlsx.save("output/spreadsheet.xlsx");
1---
2name: excel
3description: "Use this skill when a user requests to create, modify, analyze, visualize, or work with spreadsheet files (`.xlsx`, `.xls`, `.csv`, `.tsv`) with formulas, formatting, charts, tables, and recalculation."
4metadata:
5 source: https://skillmd.com/skills/bighardperson/excel
6---
7
8# Spreadsheets skill
9
10This skill includes guidelines for how to produce a correct, polished spreadsheet artifact quickly that completes the user's request. When producing spreadsheets or workbooks, you will be judged on layout, readability, style, adherence to industry norms/conventions and correctness. Follow the guidelines below for how to use the APIs effectively and how to verify your output before finalizing work for the user.
11
12For complex, analytical, financial or research involved tasks, you are especially judged on correctness and quality. You need to be professional. For these, always make sure you have a plan for how you're organizing the spreadsheet, and the data or visualizations within each sheet. For business, finance, operations, dashboard, and data-analysis prompts, aim for an output that can compete with a strong analyst-built workbook, not just a functional grid. A good default shape is an executive summary or dashboard first, then source/assumptions, then model/detail sheets. For simpler tasks like a creating template or tracker, or things that do not require research, prioritize doing the spreadsheet build and edits quickly, while ensuring the user's request is fulfilled.
13
14For additional stylistic best practices, follow: `style_guidelines.md`
15
16# Tools + Contract
17- Use the existing installed `@oai/artifact-tool` JS package which exists in the default Codex workspace dependencies node_modules for authoring, editing, inspecting, rendering, and exporting spreadsheet `.xlsx` workbooks. Use the bundled workspace Node.js and Python runtimes for local builders and helper scripts.
18- Run builder files from a writable conversation-specific temp or workspace directory, not from the managed dependency directory.
19- For JavaScript builders, do not use `NODE_PATH`; ensure bundled packages resolve through normal Node package lookup from the builder file.
20- If needed, create a local `node_modules` directory link or Windows junction to the bundled `node_modules`; do not copy bundled dependency directories or import internal package files directly.
21- Prefer to use a single executable JavaScript builder (.mjs); patch and rerun the same builder file when iterating. Do not put script bodies in shell heredocs or inline shell script bodies, or keep extra workspace-local builder copies.
22- Final user-facing response: Must include a short summary of the workbook/sheets/ranges created or edited, plus standalone Markdown link(s) only to final `.xlsx` artifact(s), with this link format `[Revenue Model - model.xlsx](/absolute/path/to/model.xlsx)`; using a platform-appropriate absolute filesystem path. If there are multiple requested final workbooks, put each final `.xlsx` Markdown link on its own line. Do not wrap final artifact links in backticks or code fences, and do not put them in bullets, headings, or prose sentences.
23- The final response summary must describe only the user-visible result. Do not mention implementation details such as `artifact_tool`, artifact-tool, `@oai/artifact-tool`, the Node/JS builder, copied builder scripts, package manifests, export workflow, verification workflow, rendered previews, or internal tooling unless explicitly requested.
24- Do not link to or mention rendered previews, copied builder scripts, intermediate JSON/CSV/log files, scratch files, or other support artifacts unless explicitly requested. Do not delete or suppress support files just to satisfy this response rule.
25- Do not use alternate workbook creation/editing libraries such as `openpyxl`, `xlsxwriter`, or `pandas.ExcelWriter` unless the user explicitly asks for a non-artifact-tool fallback.
26- For analysis outside workbook authoring, use the simplest reliable installed tool. If analysis cannot be done directly in the JavaScript script or via formulas in the spreadsheet, additional Python libraries such as `pandas`/`numpy` are available in the bundled Python runtime in the default Codex workspace dependencies. Save analysis outputs as JSON/CSV; the JavaScript builder should read those files and create the workbook with `@oai/artifact-tool`. Keep workbook-derived or user-editable calculations as spreadsheet formulas when auditability or future editing matters.
27- Use the update_plan tool to communicate your approach with the user and ensure you're staying on track to produce the best outcome for the user. Generally, your plan should emphasize speed to a correct first version, followed by incremental improvements and verification. Incrementally rendering your work and assessing overall aesthetics, formatting and correctness along the way is very important (you should rigorously inspect the output and be confident in quality), but do not get stuck in a long render-verify loop. As part of your plan, think about the best practices and conventions to follow for the specific type of spreadsheet you're creating and the best way to structure the workbook for readability and usability.
28
29# General Rules
30- Start meaningful edits quickly; avoid long upfront API exploration.
31- Core APIs are listed in the API reference section below. Use them.
32- If these skill instructions are already loaded in context, do not spend a shell turn re-reading this `SKILL.md` from disk. Move directly to the prompt, attachments, and workbook build.
33- For workbook with multiple tabs/sheets, create/populate non-formula inputs/tables and sheets prior to populating cross-sheet formulas.
34
35## Approach for quickly building a new spreadsheet
361. Setup: import `@oai/artifact-tool`, create workbook/sheets for new files.
372. Build quickly: bulk-write headers/data/formulas; then formatting/validation/conditional formatting; add charts/tables only when needed.
383. Use additional focused calls if helpful for streamed progress.
394. Near completion: inspect key ranges, scan formula errors, render all the sheets and verify, run a validation pass
405. Export `.xlsx`
41
42## Making edits on a spreadsheet
43If a user asks to edit or add to an existing spreadsheet:
44- For visual fix requests, start with the smallest plausible local change rather than applying sheet-wide autofit, wrapping, or restyling.
45- When making edits, ensure existing formulas and patterns are consistent. For example, if asked to add another column or row to a table and there is conditional formatting applied to the whole table, it should extend to the new column or rows as well.
46- If specific cells/rows/columns are specified in prompt, limit edits to those ranges unless a broader change is clearly necessary. The exceptions are when other parts of the spreadsheet depend on them, e.g. if there's a dynamic chart that is based on the range of values in a table and a new row is added, the chart should include that new row. Another example is if conditional formatting was already set for a table from A1:C5, and you add a new column D, the conditional formatting should be updated (or deleted and re-created) to cover A1:D5.
47- For column resizing, avoid autofitting by default: instead, inspect only relevant data range, measure the longest text entry in that range, and set columnWidthPx to an estimated width based on text length (with a reasonable min/max cap). Use autofit only when the user explicitly asks for it.
48
49## Handling queries and questions
50- The user may ask questions about the sheet instead of requesting an edit or a change. Simply answer those questions about the spreadsheet based on the context available rather than making an edit the user didn't intend for. You can use inspect to learn more or directly read values/formulas/tables etc via accessor methods.
51
52# Error Recovery
53On first error:
541. Read error text.
552. Run one targeted `workbook.help("<exact_api>")` query only if needed.
563. Retry with minimal patch (not full rewrite).
574. Continue from existing workbook state.
58
59Do not loop indefinitely on similar failures.
60
61# Quality Guidelines
62- Keep layout readable and bounded, contents visible:
63 - avoid extreme width/height from unconstrained autofit
64 - cap oversized widths/heights after `autofit` + `wrap_text`
65- Prefer formula-driven logic over manual painted cells when logic is expected.
66- Derived values must be formulas (not hardcoded) and legible.
67- Use absolute/relative references correctly for fill/copy behavior.
68- Do not use magic numbers in formulas; reference cells (e.g. `=H6*(1+$B$3)`).
69- Blank editable templates must look blank/neutral before user data is entered. Count, ranking, best/worst, IRR/RATE/XIRR, variance, and status formulas should guard on required input cells and return `""`, `0`, or a clear "No entries yet" state as appropriate. Alternatively, prefill with a few rows of example data.
70- Include at least one visual summary for tracker/planning requests when appropriate (KPI block, chart, dashboard area).
71- For dashboard, visualization, chart-ready analysis, budget/reporting, trend, schedule/timeline, and KPI prompts with plottable data, include at least one native Excel chart unless a verified export failure remains after simplifying the chart. Do not silently replace all charts with styled tables.
72- For presentation-ready analytical workbooks, plain range formatting alone is usually not enough. Prefer real Excel structures where useful: tables, freeze panes, filters, data validation, conditional formats, and at least one chart/KPI/dashboard visual when the prompt implies summary analysis.
73- In rendered previews of dashboards and summary sheets, check financial values and row labels at normal zoom. Widen columns, adjust row heights, or move chart panels until important numbers and text are not clipped, awkwardly wrapped, or hidden.
74
75# Completion Criteria
76Complete only when:
77- Workbook content is populated and formulas compute.
78- No obvious formula errors in key scanned ranges (no bad refs/off-by-one/circular errors).
79- `.xlsx` saved to `outputs/<unique_thread_id>/`.
80- Layout is organized, legible, and aligned to request style (or default formatting baseline).
81
82# Verification Rules
83Before final response, verify values/formulas and visual quality.
84
851. Inspect key ranges:
86```js
87const check = await workbook.inspect({
88 kind: "table",
89 range: "Dashboard!A1:H20",
90 include: "values,formulas",
91 tableMaxRows: 20,
92 tableMaxCols: 12,
93});
94console.log(check.ndjson);
95```
96
97Inspect targeting:
98- Prefer sheet-qualified ranges (`"Sheet!A1:H20"`) or `sheetId`.
99
1002. Scan formula errors:
101```js
102const errors = await workbook.inspect({
103 kind: "match",
104 searchTerm: "#REF!|#DIV/0!|#VALUE!|#NAME\\?|#N/A",
105 options: { useRegex: true, maxResults: 300 },
106 summary: "final formula error scan",
107});
108console.log(errors.ndjson);
109```
110
1113. Render sheets/ranges to verify visual output (skip if already verified and no style changes):
112```js
113const blob = await workbook.render({ sheetName: "Sheet1", range: "A1:H20", scale: 2 });
114```
115Make sure you do at least one visual pass of all the sheets in the workbook before the final export.
116
117Visual requirements:
118- Fix severe defects before finalizing: blank/broken charts, clipped key headers or numbers, unreadable colors, obvious formula errors, default blank sheets, or content outside the visible working area.
119- Ensure logical labels or titles appear once, texts are all clearly visible, and merged ranges exist where labels or content intentionally span multiple columns.
120- Do one focused visual repair pass after the initial render. Do not spend additional passes on minor polish once the workbook is correct, legible, and exported; note any minor limitation briefly and finalize.
121
1224. Keep verification compact:
123- Inspect key ranges.
124- Avoid huge NDJSON dumps.
125
1265. Export:
127```js
128await fs.mkdir(outputDir, { recursive: true });
129const output = await SpreadsheetFile.exportXlsx(workbook);
130await output.save(`${outputDir}/output.xlsx`);
131```
132
1336. Finalize immediately after successful export + compact verification.
134- Do not export extra `.xlsx` variants unless asked.
135- Do not keep iterating on alternate designs once requirements are met, unless asked.
136
137# Additional Instructions
138Read the following templates instructions ONLY when a request relates to any of the following:
139- Investment banking, company financial models, valuation, multi-statement forecasts, or source-backed financial filing analysis: templates/financial_models.md
140
141Do not load these for other tasks that are unrelated unless the prompt explicitly asks for it.
142
143# Source and PDF Extraction
144- For PDF or 10-K/10-Q style inputs, can read PDF via python library `pypdf`, if available, then use one small structured extraction script to collect all required facts into a dict/JSON object. Avoid many ad hoc `rg`/`sed` passes over the same text.
145- Keep source notes compact: record file name, section/table label, and enough context to audit the number. Do not paste large PDF excerpts into the workbook unless requested.
146
147# Using artifact_tool APIs (JavaScript)
148
149## Required Imports + Startup
150
151Import existing workbook only when needed:
152```js
153import { FileBlob, SpreadsheetFile } from "@oai/artifact-tool";
154
155const input = await FileBlob.load("path/to/input.xlsx");
156const workbook = await SpreadsheetFile.importXlsx(input);
157```
158
159Import CSV text directly when the source or intermediate data is CSV:
160```js
161import fs from "node:fs/promises";
162import { Workbook } from "@oai/artifact-tool";
163
164const csvText = await fs.readFile("path/to/input.csv", "utf8");
165const workbook = await Workbook.fromCSV(csvText, { sheetName: "Sheet1" });
166```
167Prefer `Workbook.fromCSV(...)` over hand-parsing CSV rows; clean or analyze CSV with Python/Node first only when needed.
168
169Create new workbook:
170```js
171import fs from "node:fs/promises";
172import { SpreadsheetFile, Workbook } from "@oai/artifact-tool";
173
174const workbook = Workbook.create();
175const sheet = workbook.worksheets.add("Inputs");
176```
177
178Final export:
179```js
180await fs.mkdir(outputDir, { recursive: true });
181const output = await SpreadsheetFile.exportXlsx(workbook);
182await output.save(`${outputDir}/output.xlsx`);
183```
184
185## Build Rules
186- Prefer block writes (`range.values`, `range.formulas`) over per-cell loops. Matrix shape must match the target range (for example `"D4:M4"` should be a 1x10 matrix, row x col).
187- Seed scalar formulas once, then `fillDown()` / `fillRight()`. For dynamic-array formulas (`SEQUENCE`, `UNIQUE`, `FILTER`, `SORT`, `VSTACK`, `HSTACK`), write only the anchor cell and let the result spill after.
188- Use `range.displayFormulas` plus `range.formulaInfos` when you need to understand a spill child or a data-table output cell.
189- You do not need to call recalculate; calculation automatically happens.
190- Date handling:
191 - Prefer real `Date` objects for sortable/charted/formula date columns.
192 - Apply date formats explicitly (for example `yyyy-mm-dd`).
193- Use JSON-serializable values for non-Date cells: `string | number | boolean | null`.
194- If a cell is intended to display literal text that begins with `=`, write it as a value prefixed with a single quote (for example `'=B2*C2`). This includes formula descriptions, validation examples, and labels; do not write these cells through `range.formulas`.
195- Create every worksheet referenced by formulas before writing any cross-sheet formulas.
196- When rebuilding dashboards, delete drawings first with `sheet.deleteAllDrawings()`. `range.clear()` does not remove charts, shapes, or images.
197- Verify with `await workbook.inspect(...)`; use `workbook.help(...)` only when the quick surface below is insufficient.
198
199## Conventions
200- Use camelCase API names and option keys.
201- Cell/range addressing: A1 notation (`sheet.getRange("A1:C10")`).
202- Drawing anchors (`sheet.charts`, `sheet.shapes`, `sheet.images`): 0-based `{ row, col }`.
203- Drawing offsets/extents use pixels (`rowOffsetPx`, `colOffsetPx`, `widthPx`, `heightPx`).
204
205## Discovery Policy (Strict)
206- Use this quick API surface first.
207- Use `workbook.help(...)` only when blocked by uncertainty.
208- For help queries, start with exact feature/path lookups (`chart`, `worksheet.getRange`, `worksheet.freezePanes`, `range.dataValidation`, `chart.series.add`). If an exact path fails, one broader wildcard search is allowed.
209- Do not repeat semantically similar help queries.
210- If one help query returns 0 matches, reformulate once, then proceed best-effort.
211- `render` can be used to examine an existing workbook visually and for visual verifications.
212
213Useful help calls:
214```js
215console.log(workbook.help("shape.add", { include: "examples,notes" }).ndjson);
216console.log(
217 workbook.help("*", {
218 search: "fill|borders|autofit",
219 include: "index,examples,notes",
220 maxChars: 6000,
221 }).ndjson,
222);
223```
224
225## Reading existing/imported workbooks
226- On existing/imported workbooks, get a compact summary via `inspect` to understand what already exists and where.
227- Prefer `inspect(...)` for workbook understanding and discovery across broad areas.
228- Prefer direct getters like `range.formulas` when you already know the target range and need the exact rectangular formula matrix.
229- If formula locations are unknown, prefer `inspect({ kind: "formula", ... })` over reading `range.formulas` across a very large area.
230- Prefer to set `maxChars`, `tableMaxRows`, `tableMaxCols`, and/or `maxResults` to prevent large dumps of data.
231
232### Inspect for workbook understanding
233- Compact summary:
234```js
235await wb.inspect({
236 kind: "workbook,sheet,table",
237 maxChars: 6000,
238 tableMaxRows: 6,
239 tableMaxCols: 6,
240 tableMaxCellChars: 80,
241});
242```
243- Quick overview of sheet ids and names: `await wb.inspect({ kind: "sheet", include: "id,name" })`
244- Formula discovery in a targeted area: `await wb.inspect({ kind: "formula", sheetId: firstSheetName, range: "A1:Z30", maxChars: 2500, options: {maxResults:50} })`
245- Checking existing styles in a targeted area: `await wb.inspect({ kind: "computedStyle", sheetId: firstSheetName, range: "A1:E10", maxChars: 2500 })`
246- Common `kind` tokens: `workbook`, `sheet`, `table`, `region`, `match`, `formula`, `thread`, `computedStyle`, `definedName`, `drawing`
247- Inspects can also be used to zoom in on specific areas, especially for target edits:
248```js
249await wb.inspect({
250 kind: "region",
251 sheetId: firstSheetName,
252 range: "A1:Z30",
253 maxChars: 2500,
254});
255```
256- Inspect output may include JSON records with `"id"` values (for example `"ws/r5qsk5"`), which you can resolve back to workbook objects with `wb.resolve(...)`:
257- `wb.resolve("ws/...")` -> worksheet
258- `wb.resolve("th/...")` -> comment thread
259
260## Additional feature-specific notes
261
262### Merging cells
263- Merging cells is useful for headers, dashboards, visual descriptors, and other multi-cell labels.
264- If you plan to set a range of cells to a single value, consider merging those cells first.
265For example:
266```js
267const range = sheet.getRange("I23:N24");
268range.merge();
269range.values = [["Some long description that should cross multiple cells"]];
270```
271
272## Known Gotchas (Do Not Repeat)
273- Do not set undocumented attributes on remote objects.
274- `Workbook.create()` starts with no sheets; add one before calling `getActiveWorksheet()`.
275- Use matrix sizes that match target ranges unless you intentionally spill.
276- If a formula appears unsupported, use an alternate equivalent.
277- For cross-sheet formulas in a newly created workbook, create all referenced worksheets first, then write formulas. Avoid writing formulas that reference sheets that have not been added yet.
278- Avoid full-column formula references such as `A:A`, `$A:$A`, or `Sheet!B:B`. Prefer bounded ranges sized to the editable table, e.g. `$A$6:$A$205`, especially inside `COUNTIFS`, `SUMIFS`, `INDEX`, and lookup formulas.
279- If export fails, isolate the cause by checkpoint-exporting after each major feature block: base sheets, values/formulas, formatting, conditional formatting, tables, charts/rendering. Do this before rewriting the workbook.
280- If export fails with `invalid int32: NaN` or another serialization error after formatting or charts, do not rerun the same script unchanged. First remove or simplify optional drawing/chart/style details in this order: nested/custom border configs, custom chart axis/style mutations, broad row/column formatting/autofit calls, then nonessential drawings. Preserve values/formulas and keep or retry a minimal helper-range chart when the prompt needs charts; only drop all charts/drawings if the simplified chart still prevents export.
281- Prefer fills, font hierarchy, spacing, and section bands over complex nested border objects. If you use borders, start with a minimal preset or a very simple thin/light border on a bounded range and checkpoint export before applying borders widely. Avoid nested `inside`/`around`/`outline` border configs and border `weight` settings unless you have already checkpoint-exported that exact pattern successfully.
282- For chart-heavy dashboards, checkpoint export after the first basic helper-range chart before adding multiple charts or optional axis/formatting mutations. If a chart export failure happens twice, keep the cleanest minimal chart that exports or replace the failing chart with a clearly labeled helper table/KPI block rather than spending the task on repeated chart debugging.
283- Keep formatting and formulas on bounded ranges. Avoid whole-row or whole-column formatting/autofit for generated workbooks unless you have verified the export immediately afterward.
284
285## Quick API Surface (High-Value + Common)
286
287### Core workbook/file APIs
288- `import { FileBlob, SpreadsheetFile, Workbook } from "@oai/artifact-tool"`
289- `const workbook = Workbook.create(); const sheet = workbook.worksheets.add("Sheet1")`
290- `const workbook = await SpreadsheetFile.importXlsx(arrayBufferOrFileBlob)`
291- `const xlsx = await SpreadsheetFile.exportXlsx(workbook); await xlsx.save("output.xlsx")`
292- `const inspect = await workbook.inspect({ kind: "sheet", include: "id,name", sheetId, range: "A1:C10" })`
293- `const help = workbook.help("worksheet.getRange", { include: "index,examples" })`
294- Preferred: `const blob = await workbook.render({ sheetName: "Sheet1", autoCrop: "all", scale: 1, format: "png" })`
295- To get the bytes and/or save the blob to file:
296```js
297const previewBytes = new Uint8Array(await preview.arrayBuffer());
298await fs.writeFile(`${outputDir}/preview.png`, previewBytes);
299```
300- `const workbook = await Workbook.fromCSV(csvText, { sheetName: "Sheet1" })`
301- `await workbook.fromCSV(csvText, { sheetName: "ImportedData" })`
302
303### Worksheet selection/creation
304- `workbook.worksheets.add(name)`
305- `workbook.worksheets.getItem(name)`
306- `workbook.worksheets.getOrAdd(name, { renameFirstIfOnlyNewSpreadsheet: true })`
307- `workbook.worksheets.getItemAt(index)`
308- `workbook.worksheets.getActiveWorksheet()` (only after at least one sheet exists)
309
310### Worksheet operations
311- `sheet.getRange("A1:C10")`, `sheet.getRangeByIndexes(startRow, startCol, rowCount, colCount)`, `sheet.getCell(row, col)`
312- `sheet.getUsedRange(valuesOnly?)`
313- `sheet.mergeCells("A1:C1")`, `sheet.unmergeCells("A1:C1")`
314- `sheet.freezePanes.freezeRows(1)`, `sheet.freezePanes.freezeColumns(2)`, `sheet.freezePanes.unfreeze()`
315- `sheet.tables`, `sheet.charts`, `sheet.sparklineGroups` (`sheet.sparklines` alias), `sheet.shapes`, `sheet.images`
316- `sheet.showGridLines = false`
317- `sheet.dataTables`, `sheet.conditionalFormattings`, `sheet.dataValidations`
318- `sheet.deleteAllDrawings()` removes charts, shapes, and images before a dashboard rebuild.
319
320### Range values/formulas
321- `const range = sheet.getRange("A1:C10")`
322- `range.values = [[...], ...]` (2D matrix of values)
323- `range.formulas = [["=..."], ...]`
324- `range.formulasR1C1 = [["=RC[-1]*2"]]`
325- To read: `range.values` / `range.formulas` / `range.displayFormulas` / `range.formulaInfos` (for spill/array formulas)
326- `range.write(matrixOrPayload)` (auto-sizes/spills from anchor as needed)
327- `range.writeValues(matrixOrRows)`
328- `range.fillDown()`, `range.fillRight()`
329 - `sheet.getRange("D2").formulas = [["=..."]]`
330 - `sheet.getRange("D2:D200").fillDown()`
331- `range.clear({ applyTo: "contents" | "formats" | "all" })`
332- `range.copyFrom(sourceRange, "values" | "formulas" | "all")` source and destination must have the same shape
333- `range.copyTo(destRange, "values" | "formulas" | "all")`
334- `range.offset(...)`, `range.resize(...)`, `range.getCurrentRegion()`, `range.getRow(i)`, `range.getColumn(j)`
335- `range.getRangeByIndexes(...)`, `range.getCell(...)`
336- `range.merge()`, `range.merge(true)` to merge across, `range.unmerge()`
337
338### Formatting
339- `range.format` supports `fill`, `font`, `numberFormat`, `borders`, alignments, `wrapText`
340- `range.format.autofitColumns()`, `range.format.autofitRows()`
341- `range.format.columnWidth = 18`, `range.format.rowHeight = 24`
342- `range.format.columnWidthPx = 120`, `range.format.rowHeightPx = 24`
343- `range.setNumberFormat("yyyy-mm-dd")`
344- `range.format.numberFormat = [["0"], ["0.00"], ["@"]]`
345
346### Validation + conditional formatting
347- `range.dataValidation = { rule: { type: "list", formula1: "Categories!$A$2:$A$4" } }`
348- `range.dataValidation = { rule: { type: "list", values: ["Not Started", "In Progress"] } }`
349- `sheet.dataValidations.add({ range: "B2:B100", rule: { type: "whole", operator: "between", formula1: 1, formula2: 10 } })`
350- `range.conditionalFormats.add(type, config)`
351- `range.conditionalFormats.addCustom(formula, format)`
352- `range.conditionalFormats.addCellIs({...})`
353- `range.conditionalFormats.addDataBar({...})`
354- `range.conditionalFormats.addColorScale({...})`
355- `range.conditionalFormats.deleteAll()` / `range.conditionalFormats.clear()`
356- `sheet.conditionalFormattings.add({ range, rule })`
357
358```js
359const r = sheet.getRange("B2:B20");
360r.conditionalFormats.addCellIs({
361 operator: "lessThan",
362 formula: 0,
363 format: { font: { color: "#DC2626" } },
364});
365r.conditionalFormats.addCustom("=B2<0", { fill: "#FECACA" });
366r.conditionalFormats.addColorScale({
367 minColor: "#FEE2E2",
368 midColor: "#FEF3C7",
369 maxColor: "#DCFCE7",
370});
371r.conditionalFormats.addDataBar({ color: "accent5", gradient: true });
372```
373
374### Tables
375- Rules: When adding new tables, set explicit unique names (`TasksTable`, `SummaryTable`).
376- You cannot have multiple tables over the same range. Before adding a table on an existing/imported workbook, confirm the target range does not already overlap an existing table. Prefer the initial compact `inspect` summary over a separate tables-only scan when available.
377- `const table = sheet.tables.add("A1:H200", true, "TasksTable")`
378- `table.rows.add(null, [[...], ...])`, `table.getDataRows()`, `table.getHeaderRowRange()`
379- Read tables: `sheet.tables.items` -> `Table[]`
380- Set + Getters: `table.name`, `table.style`, `table.style`, `table.showHeaders`
381- Toggles for table utilities (set/get): `table.showTotals`, `table.showBandedColumns = true`, `table.showFilterButton`
382- `table.delete()`
383
384### Charts
385- Rules: When adding or moving charts, do not cover existing data. Put charts in a reserved rectangle with blank gutter columns/rows around the chart area.
386- Fast chart path, no help lookup needed for common line/bar/scatter charts: write a compact helper range with text categories and one column per series, then chart that range.
387```js
388sheet.getRange("F4:H7").values = [
389 ["Month", "Revenue", "EBITDA"],
390 ["Jan", 100, 10],
391 ["Feb", 120, 18],
392 ["Mar", 130, 22],
393];
394const chart = sheet.charts.add("line", sheet.getRange("F4:H7"));
395chart.setPosition("J4", "Q20");
396chart.title = "Revenue and EBITDA Trend";
397chart.hasLegend = true;
398chart.xAxis = { axisType: "textAxis" };
399chart.yAxis = { numberFormatCode: "$#,##0" };
400```
401- Fast chart path from range: `const chart = sheet.charts.add("line", sourceRange)` when the source range already has headers and text x-axis labels.
402- Avoid manual `chart.series.add(...)` and `chart.legend = {...}` on the first pass, unless source-range based chart creation does not work (for example, non-continuous data). Use a helper range chart first, then add optional chart styling only if the basic chart renders and exports cleanly.
403- If you want to set specific chart props after the helper-range path is not enough: `const chart = sheet.charts.add("bar", chartProps)`, then checkpoint export before adding optional styling.
404- If using compat positioning, always set position: `chart.setPosition("F2", "M20")`.
405- `sheet.charts.getItemOrNullObject("Chart 1")`, `sheet.charts.deleteAll()`
406- To update x/y-axis, prefer compact config assignments such as `chart.xAxis = { axisType: "textAxis", tickLabelInterval: 2 }` and `chart.yAxis = { numberFormatCode: "$#,##0" }`. These help legibility and visibility.
407- For month/date x-axes, prefer a chart helper range with text labels such as `Jan 2025` or `2025-01`. Do not rely on date axis number formats alone; rendered previews can show Excel serial numbers.
408- Chart types: `"bar" | "line" | "area" | "pie" | "doughnut" | "scatter" | "bubble" | "radar" | "stock" | "treemap" | "sunburst" | "histogram" | "boxWhisker" | "waterfall" | "funnel" | "map"`.
409
410### Sparklines
411- `sheet.sparklines.add({...})`, `sheet.sparklines.clear()`, `sheet.sparklines.deleteAll()` (`sheet.sparklineGroups` is the worksheet-scoped alias)
412
413### Help / Grep
414Use `workbook.help(...)` primarily for obscure/advanced surfaces (for example deep chart axis settings, unusual drawing configs, pivot APIs, or uncommon option schemas).
415- `workbook.help("enum.ShapeGeometry", { include: "index,notes" }).ndjson`
416- `workbook.help("enum.*", { search: "ShapeGeometry|LineStyle", include: "index" }).ndjson`
417- `workbook.help("shape.add", { include: "examples,notes" }).ndjson`
418- `workbook.help("*", { search: "fill|borders|autofit", include: "index,examples,notes", maxChars: 6000 }).ndjson`
419
420
421### JavaScript example snippet (runnable)
422
423```js
424import fs from "node:fs/promises";
425import { SpreadsheetFile, Workbook } from "@oai/artifact-tool";
426
427async function quickApiExample() {
428 const workbook = Workbook.create();
429 var sheet = workbook.worksheets.add("ExampleSheet");
430
431 sheet = workbook.worksheets.getItem("ExampleSheet");
432 sheet.getRange("A1:D4").values = [
433 ["Name", "Personality Type", "Age", "Birthday"],
434 ["John Doe", "Introvert", 30, new Date("1990-01-01T00:00:00Z")],
435 ["Jane Smith", "Extrovert", 25, new Date("1995-02-15T00:00:00Z")],
436 ["Jim Very Long Name", "Ambivert", 40, new Date("1980-03-20T00:00:00Z")],
437 ];
438 sheet.getRange("E1").values = [["Score"]];
439 sheet.getRange("E2").formulas = [["=C2*10"]]; // score is 10 * age
440 sheet.getRange("E2:E10").fillDown();
441 const headerRange = sheet.getRange("A1:E1");
442
443 // Styling
444 const headerFormats = {
445 fill: "#0F766E",
446 font: { bold: true, color: "#FFFFFF" },
447 horizontalAlignment: "center",
448 verticalAlignment: "center",
449 rowHeight: 16,
450 };
451 headerRange.format = headerFormats;
452 headerRange.format.autofitColumns();
453
454 const dataRange = sheet.getRange("A2:D10");
455 dataRange.format.wrapText = true;
456 sheet.showGridLines = false;
457
458 // Format dates properly.
459 sheet.getRange("D2:D10").format.numberFormat = "MM/DD/YYYY";
460
461 // Conditional formatting
462 sheet.getRange("C2:C10").conditionalFormats.addDataBar({
463 color: "#704023",
464 gradient: true,
465 });
466 sheet.getRange("E2:E10").conditionalFormats.add("cellIs", {
467 operator: "greaterThan",
468 formula: 300,
469 format: { font: { color: "#B91C1C" } },
470 });
471 sheet.conditionalFormattings.add({
472 range: "B2:B10",
473 rule: {
474 type: "expression",
475 formula: '=B2="Introvert"',
476 format: { fill: "#FCA5A5" },
477 },
478 });
479
480 // Data validation: Since Personality Type is a dropdown category, add data validation.
481 sheet.getRange("B2:B10").dataValidation = {
482 rule: {
483 type: "list",
484 values: ["Introvert", "Extrovert", "Ambivert"],
485 // formula1: "CategoriesSheet!$A$2:$A$4", // Alternative: reference a tunable list
486 },
487 };
488
489 // Tables: Turn it into a table (for example purposes! Make sure table names are unique)
490 // NOTE: If hasHeaders=true, the range must include the header row.
491 const table = sheet.tables.add("A1:E10", true, "PeopleTable");
492 table.getHeaderRowRange();
493
494 // First column is still wide since we only auto-fit the first row. Expand it manually.
495 sheet.getRange("A1:A10").format.columnWidth = 20;
496
497 // Create charts to the right of the table
498 sheet.getRange("H1:O1").merge();
499 sheet.getRange("H1").values = [["Charts"]];
500 sheet.getRange("H1").format = headerFormats;
501
502 // Adding charts
503 const chart = sheet.charts.add("bar", {
504 from: { row: 1, col: 7 },
505 extent: { widthPx: 620, heightPx: 320 },
506 });
507 chart.title = "Person by Scores";
508 chart.hasLegend = true;
509 chart.displayBlanksAs = "zero";
510 chart.legend.position = "right";
511 chart.barOptions.direction = "column";
512 chart.barOptions.grouping = "clustered";
513 const sheetRef = sheet.name.replaceAll("'", "''");
514 const dataEndRow = 4; // Keep chart refs to rows with data only.
515
516 const scoreSeries = chart.series.add("Scores by Person");
517 scoreSeries.categoryFormula = `'${sheetRef}'!$A$2:$A$${dataEndRow}`;
518 scoreSeries.formula = `'${sheetRef}'!$E$2:$E$${dataEndRow}`;
519 scoreSeries.valuesFormatCode = "0";
520 chart.setPosition("H2", "O16");
521
522 // Granular control over chart axes
523 chart.xAxis = {
524 axisType: "textAxis",
525 title: { text: "Person", textStyle: { fontSize: 13, bold: true } },
526 position: "bottom",
527 orientation: "minMax",
528 textStyle: { fontSize: 10 },
529 };
530 chart.yAxis = {
531 axisType: "textAxis",
532 title: { text: "Scores", textStyle: { fontSize: 13, bold: true } },
533 numberFormatCode: "0,000",
534 numberFormatSourceLinked: false,
535 };
536
537 // Chart 2 - Fastest path with defaults
538 const chart2 = sheet.charts.add("line", sheet.getRange("B2:C4"));
539 chart2.title = "Scores by Personality";
540 chart2.setPosition("H20", "O35");
541
542 // Sparklines: add to the right of table
543 const sparklinesHeader = sheet.getRange("F1");
544 sparklinesHeader.values = [["Sparklines"]];
545 sparklinesHeader.format = headerFormats;
546 sparklinesHeader.format.autofitColumns();
547
548 sheet.sparklines.add({
549 type: "column", // "line" | "column" | "stacked"
550 sourceData: sheet.getRange("E2:E10"),
551 targetRange: sheet.getRange("F2:F10"),
552 seriesColor: "#AAAAAA",
553 });
554
555 // Render
556 await fs.mkdir("output", { recursive: true });
557 const pngBlob = await workbook.render({
558 sheetName: "ExampleSheet",
559 autoCrop: "all",
560 scale: 1,
561 format: "png",
562 });
563 const pngBytes = new Uint8Array(await pngBlob.arrayBuffer());
564 await fs.writeFile("output/example_sheet.png", pngBytes);
565 console.log("Rendered first sheet to 'output/example_sheet.png'");
566
567 // Export
568 const out = "output/example_sheet.xlsx";
569 const xlsx = await SpreadsheetFile.exportXlsx(workbook);
570 await xlsx.save(out);
571}
572
573await quickApiExample();
574```
575
576Render:
577```js
578const imageBlob = await workbook.render({
579 sheetName: "ExampleSheet",
580 autoCrop: "all",
581 scale: 1,
582 format: "png",
583});
584```
585
586Export:
587```js
588const xlsx = await SpreadsheetFile.exportXlsx(workbook);
589await xlsx.save("output/spreadsheet.xlsx");
590```