xlsx
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.
1实现原理 · 为什么它能做到
与 docx/pptx 同哲学：按任务选工具——带公式/格式的创建编辑走 openpyxl，批量数据走 pandas，快速浏览走 markitdown，读『公式+值』模型必须双次 load_workbook。
| **Read** a model (formulas *and* values) | two `load_workbook` passes — see gotchas
核心工程事实：openpyxl 只写公式字符串不带缓存值，凡含公式文件交付前必须 recalc.py——它驱动 LibreOffice 以 StarBasic 宏重算并原地重写文件，返回带 status/errors_found 的 JSON 契约。
openpyxl writes formulas as strings with **no cached values**. Until you recalculate, every formula cell reads back as `None` to anything reading cached values
公式可移植性被当作交付质量：LO 实现的函数子集<Excel，写不进 _xlfn. 前缀或不支持的函数会变成 #NAME? 烤进交付文件，所以有一张『能用/需前缀/禁用』三档函数清单。
LibreOffice implements fewer functions than Excel, and one it cannot evaluate becomes a literal `#NAME?` baked into the file you deliver.
『绿色 recalc ≠ 公式正确』被显式化：误差范围错、引错行的公式照样 0 错通过，要求先写 2-3 条公式抽验值再铺网格。
**A green recalc proves your formulas *evaluate*, not that they are *right*.**
外链引用（'[1]Returns Analysis'!$B$2）被识别为高危：openpyxl 重存会丢缓存值、LO 再解析会失败并删除全部链接——recalc.py 检测到外链直接拒跑，需先拷值或 --force 接受损失。
if you re-save it with openpyxl and then recalculate. Such a formula reads `='[1]Returns Analysis'!$B$2`
交付物纪律成体系：专业字体、每条假设/硬编码数字留注释或邻格并注明出处、自建待填工作簿要带 legend+示例行、改既有文件只写它的输入格且不动公式、按用户字面规格做。
**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.
2核心能力
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| package | openpyxl / pandas / markitdown（pip，预装声明，import 失败才装） |
| cli | LibreOffice soffice（recalc 引擎，经 scripts/office/soffice.py 包装，适配无头沙箱） |
| cli | gtimeout（可选，recalc 超时保护） |
4管控建议与判定依据
- scripts/: 执行本地脚本或命令: recalc.py（自带 python）→ 经 soffice.py 启动 LibreOffice headless 执行内嵌 Basic 宏（cal
- 本地工作目录: 文件读写与工件输出: recalc 原地重写工作簿（-env:UserInstallation 临时 LO profile 在 tempdir）
5第二遍独立确认
- [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' 负面边界明确。
- [ok] 元数据 — 本地 HEAD==pin 41bbe19；LICENSE 专有（© 2025 Anthropic, PBC.）与 frontmatter 'Proprietary' 一致。
6结论
d680b3f18f0c671a…