The xlwings Lite AI Coder Instruction File - December 2025 Release

Published: December 7, 2025

xlwings Lite turns Excel into a live Python app. No Python install on the user's machine. Just a browser-based add-in with code editor, console, and deep Excel integration. It launched earlier this year and I've been using it ever since.

When you use AI coders like Claude, Cursor, or Gemini to write xlwings Lite code, they don't know its constraints. They generate desktop xlwings syntax that looks right but fails silently. So I started maintaining an instruction file - a document you feed to the AI before it writes code, teaching it what works and what doesn't in xlwings Lite's environment.

Started as a handful of rules. Went to 1,450 lines by July. Now at 1,867 lines. The additions are patterns I had to figure out over five months of client work and tool builds.

Latest client build using this file: A data cleaning workflow for a team of 4-5 domain experts. They connect to a read-only database view, filter by date range and segment, pull records. An LLM module runs and shares suggestions for each record. The domain folks review, tag off wherever the AI suggestions are acceptable, adjust where needed. The script generates a CSV that goes to the data guy for final validation before the actual backend update. Users never touch the live database directly - read-only access, manual validation step, then the data guy does the insert. Built the whole thing in xlwings Lite with the instruction file guiding the AI coder. Took a fraction of the time it would have otherwise.

For more open-source builds and public tools, see the sections below.

What's in the December 2025 Version

21 Golden Rules (was 5 when I started off)

These are the non-negotiable patterns. Violate any of them, and your script either fails or produces garbage. Examples:

• Never use .expand() on data you just wrote. Excel hasn't registered it yet. Use .resize() with explicit dimensions instead.
• Never write 2D Python lists to a single cell. Causes silent InvalidArgument errors. Write cell-by-cell.
• Never mix numbers and empty strings in a DataFrame column. Use None for missing numeric values, or convert the whole column to string.
• Never access a Table's parent sheet with .sheet - the attribute doesn't exist in xlwings Lite. Use the helper function that searches all sheets.

Each rule exists because I hit the problem on a live project. Documented the failure mode. Added the fix.

InvalidArgument Troubleshooting Guide

This error shows up in the Excel UI with zero Python traceback. Top three causes, in order of likelihood:

• Mixed data types in a DataFrame column (most common - the number vs empty string problem)
• Sheet state contamination from manual renaming (user renamed an output sheet, API gets confused)
• General API instability requiring a forced roundtrip before table creation

The guide walks through diagnosis and fixes for each. Before this section existed, I had to constantly look into the codes and keep reminding AI.

Custom Function Patterns

The @func decorator for Excel custom functions has a gotcha: if your type hint says float and the Excel cell contains text or is blank, you get #VALUE!. The fix is using typing.Any and converting inside the function.

API Stability Workarounds

xlwings Lite talks to Excel through a JavaScript bridge. Sometimes the API state gets out of sync. The 'API Sync' pattern forces a roundtrip before critical operations - write a dummy value, read it back, then proceed. A bit messy, but it works.

xlwings Lite Limitations

The instruction file has the complete list. When your AI Coder knows the boundaries upfront, you design around them instead of discovering them mid-project.

• sheet.autofit() - NotImplementedError
• Range.current_region - Not implemented
• Range.merge() / Range.unmerge() - Not implemented
• No direct database connections (need a web API layer)
• No multiprocessing or threading
• book.save() doesn't exist

The 4 System Constraints

Highest priority. AI must verify against these before outputting code. These four will save you and your AI Coder the most debugging time per line of instruction.

• No indexes when writing DataFrames - Always .options(index=False)
• Robust sheet deletion - Check existence before deleting, create fresh
• No autofit - Use explicit column widths or defaults
• No RGB tuples for colors - Use hex strings like '#F0F0F0'

What I've Built With This

Working apps, all available with files and docs at the xlwings Lite Practice Lab xlwings-lite.tigzig.com

• AI Web Scraper - Paste URLs, define extraction rules in plain English. Jina AI fetches pages, Gemini extracts structured data into Excel tables.
• AI Technical Analyst - Yahoo Finance data to charts to Gemini Vision analysis to PDF reports. End-to-end.
• MF Holdings Analyzer - Processes monthly mutual fund portfolio disclosures (India market). Standardizes names, merges ISINs, flags data issues for human review, outputs consolidated summary with charts. Two-stage workflow with human-in-the-loop quality control.
• Database Connector - Connect to remote databases through a FastAPI layer. Browse schema, run queries, all from Excel.
• EDA + ML Workflow - Dynamic plots, summary tables, XGBoost model with decile analysis and gains charts.

How to Use the Instruction File

• Download from the xlwings Lite Practice Lab at app.tigzig.com
• Upload to your AI coder - Cursor, Claude Code, Gemini CLI, Google Antigravity.
• Google AI Studio with Gemini 2.5 Pro works well (free tier, 1M context) for quick uses.

The file has two versions: AI-optimized (for machine consumption) and Human-readable (same content, better formatting for reference).

Do You Need to Know Python?

It helps. But you can start without it. The actual skill isn't writing code. It's designing the analytics, spotting data problems, validating results, and making it work in the real world. That's the expertise AI can't replace. If you're an analyst who's never touched Python, you'll learn what you need by doing. The instruction file handles the xlwings-specific gotchas. Your domain knowledge handles the rest.

The 5 Hard Rules for AI-Assisted Coding

Same rules I follow for any AI coder work, not just xlwings:

• Be specific - Vague instructions produce vague code
• Iterate - One step at a time. Validate. Debug.
• Review - Demand a plan and pseudocode. Interrogate AI
• Validate - Test it. Break it. Fix it.
• AI Audit - Final pass in a fresh session catches what you missed

Resources

• AI Coder Instructions file, live tools and guides at xlwings Lite Practice Lab - xlwings-lite.tigzig.com
• xlwings Lite Official Docs: lite.xlwings.org

xlwings Lite official site: lite.xlwings.org