excel

Excel Skill

Inspection

After fetching an Excel file with read_document, run excel inspect <file> first via run_bash. This shows: sheet names, dimensions, merged cell regions, detected header row, and a data preview. Review the output carefully before writing any processing code.

Data Boundary Detection

Excel sheets often have metadata, titles, or blank rows above the actual data table. Do NOT assume row 1 is the header. Look for these signals:

• Title/metadata rows: single cell with text spanning merged columns, followed by blank rows
• Header row: the first row where most cells are non-empty and contain short text labels
• Data start: the row immediately after the header
• Data end: last consecutive non-empty row (ignore trailing blanks or footnotes)
• Blank columns on the left: skip leading empty columns to find the actual data range

Use excel headers <file> for auto-detected headers per sheet. If detection looks wrong, use excel rows <file> <sheet> 1:20 to see raw top rows and determine the real header row.

Merged Cell Handling

Merged cells are common in headers (e.g., "Revenue" spanning B-D as a group header with "Jan", "Feb", "Mar" in the row below). They also appear in data rows for grouping.

The excel CLI automatically fills merged regions with the top-left cell's value.

When writing openpyxl code yourself:

• Access merged ranges via ws.merged_cells.ranges
• A merged cell's value lives only in the top-left cell; others return None
• Unmerge and forward-fill before reading data:

  for merge in list(ws.merged_cells.ranges):
      val = ws.cell(merge.min_row, merge.min_col).value
      ws.unmerge_cells(str(merge))
      for r in range(merge.min_row, merge.max_row + 1):
          for c in range(merge.min_col, merge.max_col + 1):
              ws.cell(r, c).value = val
  

• Multi-level headers (merged group headers + sub-headers below): read both rows and combine them, e.g., "Revenue | Jan" becomes column name "Revenue - Jan"