# How to Work with Excel Files Using the xlsx Skill: A Complete Guide

> Master Excel files with the xlsx skill. This guide covers creating editing reading and validating workbooks using pandas openpyxl and LibreOffice for seamless data handling.

- Repository: [Anthropic/skills](https://github.com/anthropics/skills)
- Tags: how-to-guide
- Published: 2026-02-16

---

**The xlsx skill provides a complete workflow for creating, reading, editing, and validating Excel workbooks using pandas for data manipulation, openpyxl for formula injection, and LibreOffice for error-free formula recalculation.**

The xlsx skill in the `anthropics/skills` repository offers a robust, standardized approach to work with Excel files using the xlsx skill architecture. This self-contained module separates concerns between human-readable specifications, Python data libraries, and automated formula validation to ensure zero-error outputs.

## Core Architecture of the xlsx Skill

The skill separates three distinct concerns to maintain reliability and consistency:

### Guidance and Standards

The human-readable specification lives in [`skills/xlsx/SKILL.md`](https://github.com/anthropics/skills/blob/main/skills/xlsx/SKILL.md). This file defines required fonts, error-free formulas, template preservation rules, and the step-by-step process that every agent must follow when manipulating Excel files.

### Python Libraries

- **pandas** serves as the default for bulk data manipulation, including loading, summarizing, and writing tabular data.
- **openpyxl** handles low-level workbook operations such as inserting formulas, applying styles, and managing multiple sheets. The specification explicitly recommends openpyxl whenever formulas or formatting are required.

### Formula Recalculation Engine

LibreOffice evaluates Excel formulas that openpyxl cannot compute. The helper script [`skills/xlsx/scripts/recalc.py`](https://github.com/anthropics/skills/blob/main/skills/xlsx/scripts/recalc.py) installs a tiny StarBasic macro, launches LibreOffice headless, forces a full workbook calculation, and parses the resulting file for error codes (`#REF!`, `#DIV/0!`, etc.). The script returns a JSON summary that agents use to decide whether additional fixes are required.

## Step-by-Step Workflow to Work with Excel Files

Because the skill enforces **zero formula errors**, the recalc step is mandatory for any workbook containing formulas.

1. **Pick the right library** – Use pandas for quick data extraction, openpyxl when you need to preserve or inject formulas.
2. **Create or load a workbook** – Either start from `Workbook()` or call `load_workbook()` with `data_only=False` to keep formulas intact.
3. **Write data and formulas** – Follow the "Never hard-code calculated values" rule; insert Excel formulas as strings (e.g., `'=SUM(A2:A10)'`).
4. **Save the file** – `wb.save('myfile.xlsx')`.
5. **Recalculate** – Run `python scripts/recalc.py myfile.xlsx [timeout]`. The script updates all formula results and produces a JSON error report.
6. **Validate** – Parse the JSON; if `status` is `errors_found`, fix the reported cells and repeat step 5.

## Practical Code Examples

### Loading and Modifying Existing Workbooks

This example demonstrates using pandas for data analysis and openpyxl for formula injection:

```python
import pandas as pd
from openpyxl import load_workbook

# Load data (first sheet) with pandas

df = pd.read_excel('input.xlsx')
print(df.head())

# Add a new column that will be calculated in Excel

df['Total'] = None   # placeholder, will be filled by a formula later

# Save intermediate CSV (optional)

df.to_csv('intermediate.csv', index=False)

# Load the workbook with openpyxl to inject the formula

wb = load_workbook('input.xlsx')
ws = wb.active

# Assuming data starts at row 2 and column A

last_row = ws.max_row
ws[f'D{last_row+1}'] = '=SUM(C2:C{last_row})'   # Excel formula, not a Python value

# Save the updated workbook

wb.save('output.xlsx')

```

### Creating New Workbooks with Formatting

This example creates a formatted financial model from scratch:

```python
from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment

wb = Workbook()
ws = wb.active
ws.title = 'Revenue'

# Header row

headers = ['Year', 'Revenue ($mm)']
for col, header in enumerate(headers, start=1):
    cell = ws.cell(row=1, column=col, value=header)
    cell.font = Font(bold=True, color='FFFFFFFF')
    cell.fill = PatternFill('solid', start_color='FF0000FF')
    cell.alignment = Alignment(horizontal='center')

# Sample data

data = [(2023, 150), (2024, 165), (2025, 180)]
for r, (year, rev) in enumerate(data, start=2):
    ws[f'A{r}'] = year
    ws[f'B{r}'] = rev

# Add a total row with formula

ws[f'A{len(data)+2}'] = 'Total'
ws[f'B{len(data)+2}'] = f'=SUM(B2:B{len(data)+1})'

# Adjust column widths

ws.column_dimensions['A'].width = 12
ws.column_dimensions['B'].width = 18

wb.save('financial_model.xlsx')

```

### Recalculating Formulas and Validating Output

After saving any workbook containing formulas, run the recalculation script:

```bash
python skills/xlsx/scripts/recalc.py financial_model.xlsx 30

```

Sample output (formatted for readability):

```json
{
  "status": "success",
  "total_errors": 0,
  "total_formulas": 4,
  "error_summary": {}
}

```

If errors were present, `error_summary` would list each error type with cell locations, allowing you to programmatically locate and fix them before delivering the final file.

## Key Files and Components

| File | Purpose |
|------|---------|
| [`skills/xlsx/SKILL.md`](https://github.com/anthropics/skills/blob/main/skills/xlsx/SKILL.md) | Human-readable specification: standards, workflow, and best-practice checklist. |
| [`skills/xlsx/scripts/recalc.py`](https://github.com/anthropics/skills/blob/main/skills/xlsx/scripts/recalc.py) | LibreOffice-based formula recalculation, error detection, and JSON reporting. |
| [`skills/xlsx/scripts/office/soffice.py`](https://github.com/anthropics/skills/blob/main/skills/xlsx/scripts/office/soffice.py) | Helper that configures the environment for headless LibreOffice calls (used by [`recalc.py`](https://github.com/anthropics/skills/blob/main/recalc.py)). |
| Python code using **pandas** (`import pandas as pd`) or **openpyxl** (`from openpyxl import …`) | Primary runtime dependencies for data manipulation and workbook operations. |

These components together give you a robust, repeatable way to manipulate Excel spreadsheets while guaranteeing the zero-error, formula-driven outputs required by the skill.

## Summary

- The xlsx skill enforces a strict workflow to ensure **zero formula errors** in all Excel outputs.
- Use **pandas** for bulk data operations and **openpyxl** when you need formulas, formatting, or multiple sheet management.
- Always run [`skills/xlsx/scripts/recalc.py`](https://github.com/anthropics/skills/blob/main/skills/xlsx/scripts/recalc.py) after saving workbooks with formulas to validate against error codes like `#REF!` or `#DIV/0!`.
- The specification in [`skills/xlsx/SKILL.md`](https://github.com/anthropics/skills/blob/main/skills/xlsx/SKILL.md) defines required fonts, template preservation rules, and the mandatory recalculation step.
- Never hard-code calculated values; always insert Excel formulas as strings to maintain dynamic calculation capabilities.

## Frequently Asked Questions

### What is the difference between using pandas and openpyxl in the xlsx skill?

**pandas** is optimized for bulk data manipulation—loading entire sheets, performing statistical analysis, and exporting tabular data quickly. **openpyxl** provides low-level access to Excel-specific features like formula injection, cell formatting, chart creation, and multi-sheet workbook management. According to the skill specification in [`skills/xlsx/SKILL.md`](https://github.com/anthropics/skills/blob/main/skills/xlsx/SKILL.md), you should use openpyxl whenever your workflow involves formulas or formatting requirements.

### Why is the recalc.py script mandatory for workbooks with formulas?

The [`skills/xlsx/scripts/recalc.py`](https://github.com/anthropics/skills/blob/main/skills/xlsx/scripts/recalc.py) script is mandatory because the xlsx skill enforces a **zero formula errors** policy. Openpyxl can write formulas but cannot calculate their results or detect errors like `#REF!` or `#DIV/0!`. The script launches LibreOffice in headless mode, forces a full workbook recalculation, and returns a JSON report indicating whether any cells contain error values. This validation step ensures that delivered Excel files contain only valid, computable formulas.

### How do I preserve existing formulas when loading an existing Excel file?

To preserve existing formulas when loading a workbook, use `load_workbook()` from openpyxl with the parameter `data_only=False`. This ensures that openpyxl reads the formula strings (e.g., `=SUM(A1:A10)`) rather than the cached calculated values. If you set `data_only=True`, openpyxl will read only the values that were last calculated, and any formulas will be lost when you save the file.

### Can I use the xlsx skill without installing LibreOffice?

You can use the **pandas** and **openpyxl** components of the xlsx skill without LibreOffice for basic read/write operations and formatting. However, if your workflow involves writing formulas to cells, the [`skills/xlsx/scripts/recalc.py`](https://github.com/anthropics/skills/blob/main/skills/xlsx/scripts/recalc.py) script requires LibreOffice to validate those formulas and ensure zero errors. Without this validation step, you cannot guarantee that your formulas are error-free, violating the core requirement of the xlsx skill specification.