excel-explorer

name

excel-explorer

description

Use this skill when exploring, analyzing, or understanding Excel workbooks (.xlsx). This includes tasks where the user wants to: understand a workbook's structure (sheets, named ranges, data regions); read cell values or formulas from specific ranges, rows, or columns; trace how a formula is calculated by walking its dependency tree to leaf inputs; find what cells would be affected by changing an input; understand a financial model's logic (formula patterns, assumptions, cross-sheet references); detect anomalies like hardcoded overrides in formula rows; validate that a balance sheet balances; compare time-series data period-over-period; search across sheets for values or formula functions; or explore formatting patterns. Trigger when the user references an .xlsx file and wants to understand or analyze it — not modify it. Do NOT trigger when the user wants to create, write, or edit Excel files, generate charts/visualizations, or convert between formats.

Excel Explorer

Explore Excel workbooks using the xlx CLI tool — trace formula dependencies, understand model structure, and read data with pagination. Designed for AI agents exploring financial models.

Prerequisites

Excel Explorer must be installed. Verify with:

xlx --help

If not installed:

# Option A: install globally from PyPI
uv tool install excel-explorer

# Option B: run directly without installing
uvx --from excel-explorer xlx overview "file.xlsx"

# Option C: install the latest development version from the repository
uv tool install git+https://github.com/pressw-llc/excel-explorer.git

Exploration Workflow

When given an unfamiliar workbook, follow this sequence. Each step informs the next.

Step 1: Orient — What Am I Looking At?

xlx overview "workbook.xlsx"

This returns every sheet with row/column counts, formula counts, and all named ranges. Use this to understand the workbook's architecture before diving in.

Step 2: Understand Sheet Relationships

xlx sheet-flow "workbook.xlsx"

Shows which sheets feed data to which other sheets. Identifies source sheets (raw data), sink sheets (final outputs), and isolated sheets. This reveals the model's data flow.

Step 3: Examine Specific Sheets

xlx describe "workbook.xlsx" "Sheet Name" --limit 20

Shows headers, dimensions, merged cells, and a data preview. For sheets with many formulas, also run:

xlx formula-map "workbook.xlsx" "Sheet Name" --limit 10

This groups formulas by pattern — revealing the sheet's logic without reading every cell.

Step 4: Read Data

# Read a range
xlx read "workbook.xlsx" "Sheet" "A1:D20"

# Read with formulas visible
xlx read "workbook.xlsx" "Sheet" "A1:D20" --formulas

# Read a single row with column headers
xlx read-row "workbook.xlsx" "Income Statement" 5

# Read a column (e.g., line item labels)
xlx read-col "workbook.xlsx" "Sheet" "A" --limit 30

Step 5: Trace Dependencies (The Key Feature)

To understand how a number is calculated:

xlx trace "workbook.xlsx" "Summary!B15" --depth 5

This recursively walks the formula tree, showing every input that feeds the cell. Leaf nodes marked [INPUT] are the model's hardcoded assumptions. Shared dependencies are flagged.

To see what would break if an input changed:

xlx dependents "workbook.xlsx" "Assumptions!B2"

Step 6: Find Model Inputs

xlx find-inputs "workbook.xlsx"
xlx find-inputs "workbook.xlsx" --sheet Assumptions

Returns all hardcoded cells that other cells depend on, sorted by impact (most dependents first). These are the model's drivers.

Pagination

Data-returning commands support pagination to avoid overwhelming context windows (summary commands like overview, named-ranges, sheet-flow, and validate-balance take no pagination flags; trace/dependents only take --depth):

Flag	Default	Purpose
--limit N	50	Max rows returned
--offset N	0	Skip first N rows
--max-cols N	20	Max columns returned
--col-offset N	0	Skip first N columns
--depth N	5	Max recursion for trace/dependents

Paginated commands return a metadata header indicating whether results were truncated:

file: workbook.xlsx
sheet: Summary
showing: rows 1-50 of 200
truncated: true
---

When truncated: true, increase --offset to page through remaining data.

Financial Analysis Commands

For financial workbooks, these specialized commands are available:

# Summarize all assumptions and named ranges
xlx summarize-assumptions "workbook.xlsx"

# Compare a row period-over-period (auto-detects date headers)
xlx compare-periods "workbook.xlsx" "Income Statement" 7

# Find formula anomalies (hardcoded overrides, pattern breaks)
xlx find-anomalies "workbook.xlsx" "Income Statement"

# Validate balance sheet equation (A = L + E)
xlx validate-balance "workbook.xlsx" "Balance Sheet"

Search

# Search cell values across all sheets
xlx search "workbook.xlsx" "Revenue"

# Also search inside formula strings
xlx search "workbook.xlsx" "SUMPRODUCT" --formulas

# Find cells with semantic formatting (bold, colors, borders)
xlx find-formatting "workbook.xlsx" "Sheet Name"

Command Reference

For detailed help on any command: xlx <command> --help

For the complete command reference, consult references/commands.md.

Tips for Effective Exploration

• Start broad, then narrow. Always run overview and sheet-flow before reading specific cells.
• Use formula-map before trace. Understanding the dominant patterns on a sheet makes individual traces more meaningful.
• Named ranges are important. Financial models use them for key data columns and assumptions. Check named-ranges early.
• Pagination defaults are conservative. For large workbooks, start with --limit 10 to sample, then increase.
• Formatting carries meaning. In financial models, blue fill = input assumption, bold = subtotal. Use find-formatting to surface these patterns.
• Trace is the killer feature. When asked "how is this number calculated?", trace gives the complete answer.