{
  "$schema": "https://humangarden.ai/.well-known/skill-spec.schema.json",
  "canonical_url": "https://humangarden.ai/skills/xlsx/spec.json",
  "slug": "xlsx",
  "last_tested": "2026-06-05",
  "tested_by": "humangarden",
  "verdict_one_line": "pandas + openpyxl portion runs clean and the color-coding/formula conventions are sound, but the mandatory recalc.py step hard-crashes without LibreOffice and its error scanner false-positives on text commentary",
  "fires_when": [
    "user has an .xlsx/.xlsm/.csv/.tsv file they want read, edited, or fixed",
    "user wants to build a financial model with industry-standard color coding (blue input, black formula, green cross-sheet, red external, yellow assumption)",
    "user wants to convert messy tabular data into a proper spreadsheet",
    "user wants formulas computed (SUMIFS, SUMPRODUCT, growth rates) instead of Python-side hardcoded values",
    "user references a spreadsheet by name or path in passing and wants something done to it"
  ],
  "skip_when": [
    "user wants the deliverable as a Word doc, HTML report, or Google Sheets API call",
    "user is on a system without LibreOffice and cannot install it (recalc.py is unusable, formulas stay un-evaluated)",
    "user needs human-text commentary containing strings like \"#N/A\" or \"#DIV/0!\" in cells (recalc.py's scanner will misreport them as errors)",
    "user expects working examples to ship as runnable .py files (only inline snippets ship; no requirements.txt)"
  ],
  "inputs": [
    {
      "type": "file",
      "format": "xlsx",
      "constraint": "any .xlsx/.xlsm; .csv/.tsv supported via pandas"
    },
    {
      "type": "structured-data",
      "format": "pandas DataFrame",
      "constraint": "for fresh-build workflows, an in-memory DataFrame is the typical seed"
    }
  ],
  "outputs": [
    {
      "type": "file",
      "format": "xlsx",
      "quality_note": "formulas, formatting, multi-sheet structure preserved by openpyxl write; cached values remain None until recalc.py succeeds"
    },
    {
      "type": "structured-data",
      "format": "JSON error report (from scripts/recalc.py)",
      "quality_note": "only produced when LibreOffice is available; scanner uses substring match so plain-text cells containing error tokens are false-flagged"
    }
  ],
  "installation": {
    "pip": [
      "openpyxl",
      "pandas"
    ],
    "npm": [],
    "system": {
      "macos": "brew install --cask libreoffice (REQUIRED for scripts/recalc.py to evaluate any formula)",
      "linux": "apt-get install libreoffice (or equivalent — required for recalc.py)"
    },
    "notes": "No requirements.txt or pyproject.toml ships with the skill folder; deps must be read off SKILL.md prose. recalc.py imports from a sibling 'office' package (scripts/office/) and must be run from the scripts/ parent dir or with PYTHONPATH set. The script does not handle FileNotFoundError on soffice — it crashes with a raw traceback instead of returning the documented JSON contract."
  },
  "artifacts": [
    {
      "kind": "office",
      "file": "https://humangarden.ai/spec-artifacts/xlsx/input_raw_sales.xlsx",
      "caption": "Input — 15-row Q1-Q2 sales dump (raw_sales) + 3 model assumptions + empty Q1_summary stub",
      "role": "input",
      "hero": true
    },
    {
      "kind": "office",
      "file": "https://humangarden.ai/spec-artifacts/xlsx/output_model.xlsx",
      "caption": "Output — same workbook with a revenue formula column, a SUMIFS-driven Q1 P&L sheet, and color coding (blue input / black formula / green cross-sheet / yellow assumption) per SKILL.md. Cached values are None until LibreOffice recalc.",
      "role": "output",
      "hero": true
    },
    {
      "kind": "text",
      "file": "https://humangarden.ai/spec-artifacts/xlsx/transcript.txt",
      "caption": "Full stdout/stderr including the recalc.py FileNotFoundError traceback and the substring-match false-positive demo",
      "role": "reference",
      "hero": false
    }
  ],
  "caveats": [
    "scripts/recalc.py hard-crashes with an unhandled FileNotFoundError if soffice is missing — it does NOT emit the documented JSON error contract, breaking any caller that parses stdout as JSON",
    "recalc.py error scanner uses substring match (`if err in cell.value`) — any cell whose text mentions \"#N/A\", \"#DIV/0!\", \"#REF!\" etc. as plain commentary is silently flagged as a formula error, sending the SKILL.md verify-and-fix loop on a wild goose chase",
    "openpyxl-written formulas have no cached value, so a downstream consumer that opens the file with `data_only=True` sees `None` for every formula cell until LibreOffice has touched the file at least once — the workbook looks \"empty\" in any read-only pipeline",
    "opening with data_only=True and saving silently strips all formulas (SKILL.md mentions this in Best Practices but it is one bullet buried far from the workflow section — agents reading top-down often miss it)",
    "no requirements.txt or runnable example files ship; the SKILL.md inline snippets are copy-paste, not importable, and the scripts/ folder contains only recalc.py + office/ helpers (no end-to-end build example)",
    "recalc.py relies on installing a LibreOffice user-level macro on first run — sandboxed CI without ~/Library or ~/.config write access will silently fail at setup_libreoffice_macro()"
  ],
  "needs_credentials": [],
  "source_repo": "https://github.com/anthropics/skills/tree/main/skills/xlsx",
  "human_review_url": "https://humangarden.ai/skills/xlsx/"
}