Excel Agent Workbench

Excel Agent Workbench

Core Workflow

1. Clarify the target outcome from the prompt and attachments: read-only answer, workbook edit, new workbook, conversion, data cleanup, analysis, or dashboard/model build.
2. Profile existing files before changing them. Use scripts/profile_workbook.py for a compact workbook manifest when the file is .xlsx or .xlsm; use direct CSV/TSV inspection for plain text tables.
3. Preserve user data and existing workbook structure. Make the smallest reliable edit for targeted requests; create a new output file unless the user explicitly asks to overwrite.
4. Prefer formula-driven, auditable workbooks over hardcoded derived results. Put assumptions, sources, checks, and outputs in clear places.
5. Verify before finalizing: inspect key ranges, scan formulas/errors, and visually check important sheets when creating or editing presentation-quality files.

Tool Selection

• Use the built-in Spreadsheets skill and @oai/artifact-tool when available for creating, editing, rendering, and exporting polished .xlsx artifacts. It provides workbook rendering and formula-aware inspection.
• Use bundled Python libraries for extraction, cleaning, profiling, and data analysis before workbook authoring. Prefer pandas for tabular transformations and openpyxl for workbook metadata or targeted .xlsx/.xlsm reads. Resolve the bundled Python path through workspace dependencies when system Python does not have these libraries.
• Use scripts/profile_workbook.py to summarize sheets, dimensions, formulas, tables, charts, merged cells, hidden sheets, defined names, external links, and VBA presence.
• Use scripts/audit_workbook.py to scan formulas and cells for common risks such as error values, external links, volatile functions, hidden sheets, very hidden sheets, macros, and formula-like text injection.
• Use scripts/export_sheet_csv.py when a single sheet must be converted to CSV for downstream processing or review.

Workbook Design Standards

• Put a summary/dashboard first for analytical or executive outputs, followed by source data, assumptions, calculations, and checks.
• Use real Excel tables, filters, freeze panes, data validation, conditional formatting, and native charts when they improve usability.
• Keep inputs visually distinct from formulas and outputs. Common convention: editable inputs with a light fill, formulas with neutral formatting, checks with clear pass/fail styling.
• Avoid full-column formulas in models and dashboards. Use bounded ranges sized to the data or table references.
• Guard blank templates so formulas do not show noisy #DIV/0!, #N/A, or misleading rankings before data exists.
• Treat IDs, phone numbers, account numbers, postal codes, and long numeric strings as text to avoid leading-zero loss or Excel's 15-digit precision limit.
• Record source notes for externally sourced numbers: file/site name, date retrieved when relevant, and the exact table/section used.

Editing Existing Workbooks

1. Create a backup or write a new output filename.
2. Profile the workbook and inspect the target ranges/sheets.
3. Preserve formulas, named ranges, conditional formatting, validations, filters, tables, and charts unless the request requires changing them.
4. If inserting rows/columns into structured areas, extend formulas, table ranges, conditional formats, validations, and charts consistently.
5. Do not execute macros. Preserve macros only when the user explicitly needs .xlsm output and the tool path supports safe preservation.

Security And Data Hygiene

• Treat untrusted workbooks as hostile input. Do not run macros, Power Query refreshes, external data refreshes, or linked workbook updates.
• Scan for external links, hidden/very hidden sheets, suspicious formulas, and formula-like text in exported CSV/Excel data.
• Prevent CSV/Excel formula injection when writing untrusted text. Escape user-provided text that begins with =, +, -, @, tab, or carriage return unless it is intentionally a formula.
• Avoid exposing sensitive workbook data in chat. Summarize findings and reference ranges instead of dumping large tables.

Verification Checklist

• Key outputs reconcile to source rows, assumptions, or formulas.
• Formula scan has no unexpected #REF!, #DIV/0!, #VALUE!, #NAME?, #N/A, or circular-reference symptoms.
• Workbook opens cleanly in Excel-compatible software or exports successfully via the chosen tooling.
• Important headers, values, charts, and notes are visible in rendered previews or screenshots.
• Final file path is clear and points to the generated workbook or converted output.

References

• Read references/formula-patterns.md when building formula-heavy models or dashboards.
• Read references/qa-checks.md when auditing a workbook or preparing a file for business use.