Excel / XLSX

Setup

On first use, read setup.md for integration guidelines. Ask user preferences naturally during conversation.

When to Use

User needs to read, write, or generate Excel files (.xlsx, .xls, .xlsm). Agent handles type coercion, date serialization, formula evaluation, and cross-platform quirks.

Architecture

Memory lives in ~/excel-xlsx/. See memory-template.md for structure.

~/excel-xlsx/
└── memory.md     # Preferences, tools, pain points

Quick Reference

Core Rules

1. Dates Are Serial Numbers

Excel stores dates as days since 1900-01-01 (Windows) or 1904-01-01 (Mac legacy). Check workbook date system before converting. Time is fractional: 0.5 = noon, 0.25 = 6 AM.

2. The 1900 Leap Year Bug

Excel incorrectly treats 1900 as a leap year. Serial 60 represents Feb 29, 1900 (invalid date). Account for this when calculating dates before March 1, 1900.

3. 15-Digit Precision Limit

Numbers beyond 15 digits silently truncate. Use TEXT format for: phone numbers, IDs, credit cards, any long numeric identifiers. Leading zeros also require TEXT.

4. Formulas vs Cached Values

Cells may contain both formula and cached result. Some readers return formula string, others return cached value. Force recalculation if cached values might be stale.

5. Merged Cells Are Traps

Only the top-left cell of a merged range holds the value. Reading other cells in the merge returns empty. Hidden rows/columns still contain data.

6. Cross-Platform Testing Required

Windows vs Mac Excel can differ in date system. LibreOffice/Google Sheets may not support all features. Always test roundtrip compatibility when generating files for unknown consumers.

7. Use Streaming for Large Files

Loading large files fully into RAM causes memory issues. Use streaming readers (row-by-row) for files with 100K+ rows. Empty rows at end may be padded by some writers.

Common Traps

• Type inference on read → Numbers stored as text stay text; explicit conversion needed
• Column index confusion → A=0 or A=1 varies by library; always verify convention
• Newlines in cells → \n works but cell needs "wrap text" format to display
• External references → [Book.xlsx]Sheet!A1 breaks when source file moves
• Password protection → Trivial to break; not real security; encrypt file externally if needed
• XLSM files → Contain macros (security risk); XLSB is binary (faster but less compatible)
• Shared strings → Large files reuse text indices; libraries handle this, but be aware

Format Limits

Security & Privacy