Docs & Knowledge · anthropics/skills

xlsx

Name: xlsx
Author: anthropics/skills

Use this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandWrite FileDual-pass Audit

Author anthropicsGitHub anthropics/skills ↗Stars 175386License Proprietary（skill 自带 LICENSE.txt：© 2025 Anthropic, PBC. All rights reserved. 按 Anthropic Consumer/Commercial Terms of Service 授权并附 ADDITIONAL RESTRICTIONS；非开源许可）Commit 41bbe19d1a

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Shares the same philosophy as docx/pptx: pick tools by task—use openpyxl for creation/editing with formulas/formatting, pandas for bulk data, markitdown for quick browsing, and a dual load_workbook call when reading the 'formula + value' model.

skills/xlsx/SKILL.md

| **Read** a model (formulas *and* values) | two `load_workbook` passes — see gotchas

The dual-load principle is stated explicitly in the gotchas: '`data_only=True` yields cached values with the formulas gone; the default yields formula strings with no values. One pass cannot give you both.'—a single pass in openpyxl cannot retrieve both formulas and values.

Core engineering reality: openpyxl writes only formula strings without cached values; any file containing formulas must undergo recalc.py before delivery—which drives LibreOffice via a StarBasic macro to recalculate and overwrite the file in place, returning a JSON contract with status/errors_found.

skills/xlsx/SKILL.md

openpyxl writes formulas as strings with **no cached values**. Until you recalculate, every formula cell reads back as `None` to anything reading cached values

recalc.py embeds a Basic macro 'Sub RecalculateAndSave() … ThisComponent.calculateAll() ThisComponent.store()', running in a temporary LO profile; 'JSON with an `error` key instead of a `status` means nothing was recalculated, and only that case exits non-zero'—the exit code semantics are explicitly warned.

Formula portability is treated as delivery quality: the subset of functions implemented in LO is smaller than Excel; functions lacking the _xlfn. prefix or unsupported will turn into #NAME? baked into the delivered file, hence a three-tier function list ('usable / needs prefix / forbidden') is maintained.

skills/xlsx/SKILL.md

LibreOffice implements fewer functions than Excel, and one it cannot evaluate becomes a literal `#NAME?` baked into the file you deliver.

Rules: Excel-2007 era functions (SUMIFS/INDEX/MATCH/IFERROR/SUMPRODUCT) do not need prefixes; TEXTJOIN/CONCAT/IFS/SWITCH/MAXIFS/MINIFS require the _xlfn. prefix; XLOOKUP/XMATCH/SORT/FILTER/UNIQUE/SEQUENCE are forbidden (spill arrays lack metadata, silently truncating to the top-left cell and causing recalc to report 0 errors).

'Green recalc ≠ correct formulas' is made explicit: formulas with wrong error margins or referencing incorrect rows still pass with 0 errors, requiring 2-3 sample formula checks before filling the entire grid.

skills/xlsx/SKILL.md

**A green recalc proves your formulas *evaluate*, not that they are *right*.**

Supporting discipline: 'Zero formula errors. Never ship while `recalc.py` reports `errors_found`' + 'Use formulas, never hardcoded results' + 'An error you introduced looks exactly like one you inherited' (self-verification: compare against original using data_only=True).

External link references ('[1]Returns Analysis'!$B$2) are identified as high-risk: openpyxl resaving loses cached values, and subsequent LO parsing will fail and drop all links—recalc.py refuses to run upon detecting external links, requiring copying values beforehand or using --force to accept losses.

skills/xlsx/SKILL.md

if you re-save it with openpyxl and then recalculate. Such a formula reads `='[1]Returns Analysis'!$B$2`

recalc.py's external_links_at_risk() scans xl/externalLinks/ and EXTERNAL_REF_RE patterns in formulas, returning an at_risk cell list; '`recalc.py` refuses to run in that state — copy those cells' values out of the original before you save over them'.

A systematic deliverable discipline: professional typography, comments or adjacent cells detailing sources for every assumption/hardcoded number, legends + sample rows for self-built fill-in templates, modifying only designated input cells while leaving formulas untouched in existing files, and strictly executing user specs.

skills/xlsx/SKILL.md

**Follow the user's spec literally.** Exact tab names, exact column headers, and the formula they spelled out. A redesign that computes something else fails, however elegant.

Also includes 'Document every assumption and hardcoded number where the reader will see it' and 'Find its designated input cells first…write only there, and leave every existing formula untouched.'

2Core Capabilities

01Create/edit workbooks with formulas and formatting (openpyxl), including .xlsm keep_vba/.xltx/.csv/.tsv handling

02Formula recalculation verification loop: recalc.py drives LibreOffice, reporting status/total_formulas/total_errors/error_summary via JSON

03Bulk data ingestion, export, and cleaning (pandas read_excel/to_excel)

04Quick inspection (markitdown, sheet-level text dumps)

05Formula portability governance: Excel-2007 era priority / _xlfn. prefix table / banned modern dynamic array function list

06External reference risk evaluation and execution-block protection (external_links_at_risk / --force)

07Financial modeling formatting conventions: hardcoded inputs in blue / formulas in black / cross-sheet in green / cross-file in red / key assumptions in yellow, $#,##0 with percentage/multiple/year formats

08Conventions for editing existing files: locate input cells, write only there, leave formulas untouched; self-built fill-in templates include legends and sample rows

3External Dependencies

Kind	Dependency / Endpoint
package	openpyxl / pandas / markitdown（pip，预装声明，import 失败才装）
cli	LibreOffice soffice（recalc 引擎，经 scripts/office/soffice.py 包装，适配无头沙箱）
cli	gtimeout（可选，recalc 超时保护）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Execute local script or command: recalc.py (bundled Python) → launches LibreOffice headless via soffice.py to execute embedded Basic macro (calculateAll/store)
本地工作目录: File read/write and artifact output: recalc overwrites the workbook in place (-env:UserInstallation temporary LO profile in tempdir)

Audit Notes: Runs bundled Python scripts + local LibreOffice to handle formula recalculation and file overwriting, with no outbound network traffic (except conditional pip fallback to PyPI upon import failure) and no credential access. Caveats: (1) recalc overwrites delivered files in place and relies on headless LO execution (containing an embedded Basic macro—macro contents are self-contained, performing only calculateAll+store); (2) When processing macro-enabled .xlsm or untrusted workbooks, the parsing surface lies in openpyxl/LibreOffice (the host must assess versions and sandboxing); (3) recalc refusing to run on external link scenarios is a deliberate data protection design, not a defect. Overall a local spreadsheet engineering skill with no external connection risks.

5Second-Pass Verification

[ok] recalc JSON 契约与退出码语义 — 代码返回 dict 含 status/errors_found 等键；main 中 'sys.exit(1 if "error" in result else 0)' 与 SKILL 'only that case exits non-zero' 一致。
[ok] 外链拒跑机制 — external_links_at_risk() 扫描 xl/externalLinks/ 并匹配 EXTERNAL_REF_RE，SKILL 所述 'refuses to run in that state' 有代码对应（force 分支）。
[ok] LibreOffice 宏重算 — RECALCULATE_MACRO 内嵌 'Sub RecalculateAndSave() … ThisComponent.calculateAll() ThisComponent.store()'，经临时 profile 执行。
[ok] 共享 office/ 工具树 — xlsx/scripts/office 与 docx、pptx 的对应目录 diff 零差异（同一文件副本）。
[ok] 网络/凭证零命中 — 脚本无网络调用、无 env/token 读取；pip 仅条件回退。
[ok] 夸大检查 — description 'Use this skill any time a spreadsheet file is the primary input or output' 覆盖 open/read/edit/create/convert/clean 均在正文有路线；'Do NOT trigger when…Google Sheets API integration' 负面边界明确。

6Verdict & Scenarios

Engineering of formula recalculation: The core drawback of openpyxl lacking cached values is resolved via a closed-loop recalc.py + LO macro, with a JSON contract allowing the model to self-verify deliverables.

Three-tier function compatibility list (no prefix / _xlfn. / forbidden) directly prevents delivering defective files with #NAME? or silent truncation.

External link data protection: Multi-tiered safeguard (detect → refuse to run → copy values → --force) prevents 'resave drops links' accidents.

Comprehensive deliverable discipline (zero formula errors, assumption audit trails, literal spec execution, writing only to input cells in existing files), operationalizing the habits of meticulous financial modelers into rules.

Built-in financial modeling conventions, ready for immediate structured modeling deliverables.

Best for: Suitable for 'model-grade' spreadsheet tasks in managed environments: financial models with formulas, report automation, bulk data cleaning into sheets, template population. The recalc gate + external link protection is particularly suited for mission-critical scenarios where deliverables must be immediately opened and calculated in Excel/Sheets.

Not for: Not suitable for environments without LibreOffice (verification loop unavailable); not suitable for lightweight, one-off data inspection/conversion tasks (markitdown/pandas suffice, workflow is overly heavy); not suitable for editing workbooks heavily linked to external Excel files (high risk, requires value-copy workflow); not suitable for organizations unable to accept proprietary/copyleft licensing.

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload xlsx.tar.gz

sha256: d680b3f18f0c671a…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 41bbe19d1a.