Preface¶

Colleagues who do data analysis or reporting have probably all experienced this scenario: you have a .xlsx file on hand, need to add columns, modify formulas, clean dirty data, and then export it to a standardized format. When you hand it over to a generic AI assistant, it can only either “describe how to do it” or write a Python script for you to run yourself — but the formulas are hard-coded to static values, the formatting is messed up, merged cells cause errors, and you still have to manually check everything after the changes.

The emergence of Agent Skills packages this type of domain knowledge into reusable instruction packs. Today we are introducing the xlsx Skill from Anthropic’s official repository: it is exactly the implementation behind Claude’s document capabilities for processing spreadsheets, and it is also a valuable reference example for Agents when handling structured tabular data.

What is this¶

The xlsx Skill is an Agent Skill for spreadsheet tasks, maintained by Anthropic, with its source code located in the skills/xlsx directory of the anthropics/skills repository.

Its positioning is straightforward: if the main input or output of a task is a spreadsheet file, you should enable it. It covers formats including .xlsx, .xlsm, .xltx, .csv, .tsv, supports reading, editing, creating new files, format conversion, and financial modeling with formulas.

It should be noted that this Skill uses a source-available license (not Apache 2.0 open source), and belongs to Anthropic’s document skill series alongside docx, pdf, and pptx, but the official has made it public for developers to learn how to write complex Skills.

Core Features and Highlights¶

1. Tool Selection Based on Task: openpyxl, pandas, markitdown¶

The official SKILL.md divides common operations into three paths:

openpyxl, pandas, and markitdown are pre-installed in the Skill’s runtime environment. Agents should import them directly without running pip install first; only install them if the import fails.

2. Prioritize Formulas, Forbid “Hardcoding Results”¶

This is the biggest difference between the xlsx Skill and ordinary scripts. The official requirements are:
- For summary rows, write sheet['B10'] = '=SUM(B2:B9)' instead of filling in numbers calculated by Python;
- Must run a recalculation script before delivery to ensure zero formula errors;
- Strictly follow the table names, column names, and formula literals specified by the user, and do not “optimize” them into other algorithms.

3. Built-in Formula Recalculation: recalc.py¶

openpyxl does not cache calculation results when writing formulas, and without recalculation, pandas and load_workbook(data_only=True) will read None. The Skill includes scripts/recalc.py, which calls LibreOffice to recalculate formulas in-place:

python scripts/recalc.py output.xlsx [timeout_seconds]

The script will output JSON containing status (success or errors_found), total_formulas, total_errors, and a summary of error cells. As long as there are formulas in the file, this step is mandatory.

4. Financial Model Specifications¶

If the user does not specify otherwise, the Skill has a built-in investment banking-style spreadsheet convention: blue for inputs, black for formulas, green for cross-sheet references, red for cross-file references, yellow for highlighting key assumptions; details such as currency formatting, percentages stored as decimals, and years using text are clearly stipulated. This is very practical for developers building valuation sheets and budget models.

5. Formula Compatibility List¶

The Skill clearly lists the limitations of the LibreOffice recalculation environment: prioritize functions from the Excel 2007 era (SUMIFS, INDEX, MATCH, etc.); some post-2007 functions require the _xlfn. prefix; prohibited use of functions like XLOOKUP, FILTER, SORT that cannot expand correctly in the recalculation environment. Without these reminders, Agents could easily produce files that “look correct but are full of #NAME? errors when opened”.

Installation and Activation¶

The xlsx Skill follows the universal SKILL.md format and can be used in tools that support the Agent Skills standard, such as Cursor, Claude Code, and Claude.ai. The activation methods for each platform are as follows.

Claude Code¶

Register the official plugin marketplace and install the document skill pack in Claude Code:

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

After installation, you can directly describe your task, for example: “Use the xlsx skill to add a year-over-year growth rate column to this report”.

Claude.ai¶

According to Anthropic’s official instructions, the sample Skills in the repository are already available to paid plan users; you can also upload custom Skills by following Using skills in Claude.

Cursor¶

Copy the entire skills/xlsx directory to your project’s .cursor/skills/xlsx/ (or the global directory ~/.cursor/skills/xlsx/), ensuring that the SKILL.md and scripts/ subdirectory are included. Cursor will automatically detect the Skill when it starts; you can also manually call it by entering /xlsx in an Agent conversation.

Cursor also supports importing Remote Rules from GitHub: go to Customize → Rules → Add Rule → Remote Rule (Github) and fill in the repository address.

Claude API¶

Upload or use pre-built Skills via the Skills API, which is suitable for integration into automated pipelines.

Typical Usage Examples¶

Quick Preview of a Spreadsheet¶

markitdown sales_report.xlsx

The output is segmented by ## SheetName, which is suitable for first understanding the data structure; but it does not include cell coordinates, so you cannot use it to plan precise edits.

Read a Model with Formulas (Two Loads)¶

openpyxl cannot retrieve both the formula string and cached values in a single load. The official recommendation is:

from openpyxl import load_workbook

# First load: read formulas
wb_formula = load_workbook("model.xlsx")
# Second load: read cached values (must recalculate before editing)
wb_values = load_workbook("model.xlsx", data_only=True)

Note: After using data_only=True, if you save the file, formulas will be permanently replaced with static values, which is a common mistake.

Write Formulas and Recalculate¶

from openpyxl import Workbook

wb = Workbook()
sheet = wb.active
sheet['A1'] = 'Item'
sheet['B1'] = 'Amount'
sheet['B2'] = 100
sheet['B3'] = 200
sheet['B4'] = '=SUM(B2:B3)'
wb.save('output.xlsx')

After saving, you must execute:

python scripts/recalc.py output.xlsx

Bulk Data Processing¶

import pandas as pd

df = pd.read_excel('raw_data.xlsx', sheet_name='Sheet1')
df['total'] = df['qty'] * df['price']
df.to_excel('cleaned.xlsx', index=False)

If the output file contains formulas, you still need to go through the recalc.py process.

Applicable Scenarios and Notes¶

Who it is suitable for:
- Developers or analysts who need Agents to directly produce .xlsx / .csv files;
- Scenarios where financial models, operational reports, and data cleaning pipelines are built, and formulas need to be auditable and recalculable;
- Skill authors who want to learn “how to write domain specifications into Skills” — the SKILL.md for xlsx is lengthy and detailed with constraints, making it a high-quality reference.

Inapplicable scenarios (explicitly excluded by the official):
- Main deliverables are Word, HTML reports, standalone Python scripts, or database pipelines;
- Online collaboration scenarios requiring integration with Google Sheets API.

Pitfalls to watch out for when using:
1. Merged cells can only be written to the top-left anchor point, and the rest are read-only MergedCell;
2. When saving .xlsm files, you need keep_vba=True, otherwise macros will be lost;
3. If a cross-sheet reference table name contains spaces, it must be enclosed in quotes in the formula: ='Assumptions Inputs'!$B$5;
4. When editing an existing file, you should match the original file’s input cell styles (color/fill) and do not modify existing formulas;
5. Workbooks containing external file links may have broken links after being resaved by openpyxl, and recalc.py will refuse to run.

Summary¶

The value of the xlsx Skill is not in “letting AI know how to read CSV files”, but in embedding the complete engineering specifications for spreadsheet delivery — formula writing, recalculation verification, formatting conventions, compatibility boundaries — into executable instructions for Agents. For developers who often work with Excel, adding it to Cursor or Claude Code means that after describing your needs, you will get a file that can be directly handed over to business stakeholders, rather than a semi-finished product that requires secondary fixes.

Official address: https://github.com/anthropics/skills/tree/main/skills/xlsx