[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7BYHD30974T2E9FBTJZN3R2":3,"skill-same:01M7BYHD30974T2E9FBTJZN3R2":43},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":13,"repositoryHtmlUrl":26,"repositoryHomepageUrl":6,"ownerHtmlUrl":27,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":28,"install":29,"resources":42},"01M7BYHD30974T2E9FBTJZN3R2","officecli-xlsx",null,"Use this skill any time a .xlsx file is involved -- as input, output, or both. This includes: creating spreadsheets, financial models, dashboards, or trackers; reading, parsing, or extracting data from any .xlsx file; editing, modifying, or updating existing workbooks; working with formulas, charts, pivot tables, or templates; importing CSV\u002FTSV data into Excel format. Trigger whenever the user mentions 'spreadsheet', 'workbook', 'Excel', 'financial model', 'tracker', 'dashboard', or references a .xlsx\u002F.csv filename.","makeyzhang-cpu\u002Fgeekclaw","makeyzhang-cpu","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F282184316?v=4","01M7BY92NE8R5TAVDAV2CTBGHV","01M7BY92P6TYAA1XX1E7XCX7GS",0,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fmakeyzhang-cpu\u002Fgeekclaw\u002Fblob\u002Fmain\u002Fcrates\u002Fbackend\u002Fnomifun-app\u002Fassets\u002Fbuiltin-skills\u002Fofficecli-xlsx\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: officecli-xlsx\ndescription: \"Use this skill any time a .xlsx file is involved -- as input, output, or both. This includes: creating spreadsheets, financial models, dashboards, or trackers; reading, parsing, or extracting data from any .xlsx file; editing, modifying, or updating existing workbooks; working with formulas, charts, pivot tables, or templates; importing CSV\u002FTSV data into Excel format. Trigger whenever the user mentions 'spreadsheet', 'workbook', 'Excel', 'financial model', 'tracker', 'dashboard', or references a .xlsx\u002F.csv filename.\"\n---\n\n# OfficeCLI XLSX Skill\n\n## Setup\n\nIf `officecli` is missing:\n\n- **macOS \u002F Linux**: `curl -fsSL https:\u002F\u002Fd.officecli.ai\u002Finstall.sh | bash`\n- **Windows (PowerShell)**: `irm https:\u002F\u002Fd.officecli.ai\u002Finstall.ps1 | iex`\n\nVerify with `officecli --version` (open a new terminal if PATH hasn't picked up). If install fails, download a binary from https:\u002F\u002Fgithub.com\u002FiOfficeAI\u002FOfficeCLI\u002Freleases.\n\n## ⚠️ Help-First Rule\n\n**This skill teaches what good xlsx looks like, not every command flag. When a property name, enum value, or alias is uncertain, consult help BEFORE guessing.**\n\n```bash\nofficecli help xlsx                         # List all xlsx elements\nofficecli help xlsx \u003Celement>               # Full element schema (e.g. pivottable, chart, cf)\nofficecli help xlsx \u003Cverb> \u003Celement>        # Verb-scoped (e.g. add chart, set cell)\nofficecli help xlsx \u003Celement> --json        # Machine-readable schema\n```\n\nHelp reflects the installed CLI version. When this skill and help disagree, **help is authoritative**.\n\n## Shell & Execution Discipline\n\n**Shell quoting (zsh \u002F bash).** Excel paths contain `[]`, and number formats contain `$`. Both are shell metacharacters. Rules:\n\n- ALWAYS quote element paths: `\"\u002FSheet1\u002Frow[1]\"`, not `\u002FSheet1\u002Frow[1]`.\n- Use **single quotes** for any prop value containing `$`: `numFmt='$#,##0'`.\n- For formulas with cross-sheet `!` references, use `batch` with a `\u003C\u003C'EOF'` heredoc (see Known Issues).\n- NEVER hand-write `\\$`, `\\t`, `\\n` inside executable examples. The CLI does not interpret backslash escapes; they will land in your file as literal characters.\n\n**Incremental execution.** Run commands one at a time and read each exit code. `officecli` mutates the file on every call; a 50-command script that fails at command 3 will cascade silently. One command → check output → continue.\n\n## Requirements for Outputs\n\nBefore reaching for a command, know what a good xlsx looks like. These are the deliverable standards every workbook MUST meet.\n\n### All Excel files\n\n**Zero formula errors.** Every delivered workbook MUST have ZERO `#REF!`, `#DIV\u002F0!`, `#VALUE!`, `#NAME?`, `#N\u002FA`. No exceptions — guard denominators with `IFERROR` or `IF(x=0,...)`.\n\n**Formulas, not hardcoded values.** If a number can be computed from other cells, it is a formula. Hardcoding `5000` where `=SUM(B2:B9)` belongs breaks the contract that the workbook stays live when inputs change. This is the single most important rule in this skill.\n\n**Professional font.** Use one consistent, professional font across the workbook (Arial \u002F Calibri \u002F Times New Roman). Don't mix four fonts because one sheet came from CSV.\n\n**Explicit widths.** There is no auto-fit. Any column the user will read MUST have `width` set — default 8.43 chars clips everything. Sensible starts: labels 20-25, numbers 12-15, dates 12, short codes 8-10.\n\n**Preserve existing templates.** When editing a file that already has a look, match it. Existing conventions override these guidelines.\n\n### Visual delivery floor (applies to EVERY workbook)\n\nBefore you declare done, run `officecli view \"$FILE\" html` and Read the returned HTML path to confirm all of these:\n\n- **No `###` in any cell.** `###` means a column is too narrow for its widest value. Every column the user reads needs an explicit `width`. `###` in a delivered file is unfinished work, never \"a small visual nit\".\n- **No truncated titles.** Sheet titles, section headers, long labels must fit. Widen the column or apply `wrapText=true` on the cell.\n- **No placeholder tokens rendered as data.** `$fy$24`, `{var}`, `\u003CTODO>`, `xxxx` must never appear in a cell, chart title, series name, or legend. These are build-time tokens that escaped replacement.\n- **Pie \u002F doughnut slices have distinct fill colors.** If the slices render same-colored, switch to `bar` \u002F `column` or set `colors=...` explicitly.\n- **No empty trailing pages \u002F empty chart anchors.** `anchor=D2:J18` over empty source cells looks like a broken chart.\n\nIf any of the above fails, STOP and fix before declaring done.\n\n**Print layout.** Any sheet the user may print or send as a board pack needs page setup. Default portrait + no fit-to-page splits wide tables and charts mid-way. Apply per sheet:\n\n```bash\nofficecli set \"$FILE\" \"\u002FSummary\" --prop orientation=landscape --prop fitToPage=true\n```\n\nTrigger: sheet holds a chart, or > 8 columns, or the user's ask mentions print \u002F board \u002F investor.\n\n### Financial models only — skip this section if you are building a template, tracker, CSV import, or operational sheet\n\nScope: budgets, forecasts, 3-statement models, valuation, any `$`-heavy analytical workbook. A customer-support tracker or onboarding template does not need this section.\n\n**Color coding — industry standard.** Five core colors used as a language, not decoration. A reviewer should tell what a cell IS by color alone — before reading the formula.\n\n| Color | Role | Example |\n|---|---|---|\n| Blue text `0000FF` | Hardcoded inputs, scenario variables | `font.color=0000FF` |\n| Black text `000000` | ALL formulas and calculations | default |\n| Green text `008000` | Cross-sheet links inside this workbook | `font.color=008000` |\n| Red text `FF0000` | Links to external files \u002F workbooks | `font.color=FF0000` |\n| Yellow fill `FFFF00` | Key assumptions needing review | `fill=FFFF00` |\n\nA reviewer should tell what a cell IS just by its color — before reading the formula. This is a communication contract, not a cosmetic preference.\n\n**Number formatting — standards, not preferences.**\n\n- **Years** are text, not numbers. Format `2026` not `2,026` — use `numFmt=\"@\"` or set `type=string`.\n- **Currency** carries its unit in the header (`Revenue ($mm)`), not in every cell.\n- **Zeros display as `-`**, not `0`. Use `$#,##0;($#,##0);\"-\"`.\n- **Percentages** default to one decimal: `0.0%`.\n- **Negatives use parentheses**: `(1,234)` not `-1,234`.\n- **Valuation multiples** use `0.0x` format (EV\u002FEBITDA, P\u002FE, etc.).\n\n**Assumptions live in cells, not inside formulas.** `=B5*(1+$B$6)` is correct; `=B5*1.05` is a bug. Document each blue hardcoded input with an adjacent source note in the next cell or a cell comment:\n\n```\nSource: Company 10-K, FY2024, Page 45, Revenue Note\nSource: Bloomberg, 2026-05-02, AAPL US Equity\nSource: Management guidance, Q2 2026 earnings call\n```\n\nAny hardcoded number without a source is an undocumented assumption — a reviewer cannot audit it.\n\n## Common Workflow\n\nSix steps. Every non-trivial build follows this shape.\n\n1. **Choose the mode.** Always use `officecli open \u003Cfile>` at the start and `officecli close \u003Cfile>` at the end. Resident mode is the default, not an optimization — it avoids re-parsing the file on every command. For many cells, use `batch`: **≤ 50 ops\u002Fblock recommended; tested up to 80+ ops per block on pure value-set payloads with zero failures. Cross-sheet formula batches are the exception — run those non-resident, single heredoc (see Known Issues)**.\n2. **Create or load.** `officecli create \"$FILE\"` (new) or `officecli view \"$FILE\" outline` (existing — get the lay of the land first).\n3. **Build incrementally.** One command, read the output, continue. After any structural op (new sheet, chart, named range, pivot), run `get` on it to confirm shape before stacking more on top.\n4. **Format.** Column widths, number formats, freeze panes, tab colors, header fills. Formatting is not optional polish — per \"Requirements for Outputs\" it is part of the deliverable.\n5. **Close, then reckon with the cache.** `officecli close \u003Cfile>` writes to disk. Newly-added formulas ship without cached values; when a human opens the file in a spreadsheet app, the app recalculates and populates them. **But your downstream `INDEX\u002FMATCH`, `SUMPRODUCT`, or any formula that references an upstream formula will cache whatever the upstream cached at write-time — often `0` or a stale value — and that cached lie survives into non-recalculating readers.** After any multi-formula build involving array formulas (`SUMPRODUCT`, `SUMIFS` with dynamic criteria) or cross-sheet chains, **re-touch every downstream cell** (run `set` again with the same formula) so the engine recomputes its cache from the freshly-cached upstream. ⚠️ Re-touch on cross-sheet chains via resident is unreliable (see Batch \u002F resident caveats) — prefer non-resident `set` for the re-touch pass. Then `officecli get` a few downstream cells and eyeball that their `cachedValue=` is plausible. **Array-formula fallback:** for `SUMPRODUCT(1\u002FCOUNTIF(range, range))` distinct-count patterns, the CLI engine treats the inner division as scalar and caches `1\u002FN` (e.g. `0.001543`) rather than the true distinct count. Re-touching won't fix it. **Fallback: hardcode the correct value + an adjacent comment `\"hardcoded distinct count; update if Data rows change\"`, and tell the reader at delivery**. Better than shipping a cached lie. Do NOT run `validate` while a resident is open — it reports spurious drawing errors.\n6. **QA — assume there are problems.** See the QA section. You are not done when your last command exited 0; you are done after one fix-and-verify cycle finds zero new issues.\n\n## Quick Start\n\nMinimal viable xlsx: 3 months of revenue + a total formula + column widths + a currency format. Adapt, don't copy-paste — your file, your data.\n\n```bash\nofficecli create \"$FILE\"\nofficecli open \"$FILE\"\nofficecli set \"$FILE\" \u002FSheet1\u002FA1 --prop value=Month --prop bold=true\nofficecli set \"$FILE\" \u002FSheet1\u002FB1 --prop value=Revenue --prop bold=true\nofficecli set \"$FILE\" \u002FSheet1\u002FA2 --prop value=Jan\nofficecli set \"$FILE\" \u002FSheet1\u002FA3 --prop value=Feb\nofficecli set \"$FILE\" \u002FSheet1\u002FA4 --prop value=Mar\nofficecli set \"$FILE\" \u002FSheet1\u002FB2 --prop value=42000 --prop numFmt='$#,##0'\nofficecli set \"$FILE\" \u002FSheet1\u002FB3 --prop value=45000 --prop numFmt='$#,##0'\nofficecli set \"$FILE\" \u002FSheet1\u002FB4 --prop value=48000 --prop numFmt='$#,##0'\nofficecli set \"$FILE\" \u002FSheet1\u002FA5 --prop value=Total --prop bold=true\nofficecli set \"$FILE\" \u002FSheet1\u002FB5 --prop formula=\"SUM(B2:B4)\" --prop bold=true --prop numFmt='$#,##0'\nofficecli set \"$FILE\" \"\u002FSheet1\u002Fcol[A]\" --prop width=12\nofficecli set \"$FILE\" \"\u002FSheet1\u002Fcol[B]\" --prop width=15\nofficecli close \"$FILE\"\nofficecli validate \"$FILE\"\n```\n\nVerified: `validate` returns `no errors found`, `B5` resolves to `135000`. This is the shape of every build: open → set cells\u002Fformulas → format → close → validate.\n\n## CSV \u002F bulk import\n\n**Native `import` command (preferred for CSV\u002FTSV).** Fastest path; loads a CSV into a sheet in one call. `--header` sets AutoFilter + freeze pane on row 1. Widths and `numFmt` still need a follow-up pass (per D-12 in Dashboard skill).\n\n```bash\nofficecli import \"$FILE\" \u002FSheet1 --file data.csv --header\nofficecli import \"$FILE\" \u002FSheet1 --file data.tsv --format tsv --header\nofficecli import \"$FILE\" \u002FSheet1 --stdin --start-cell B2 \u003C data.csv\n```\n\n**Python + batch fallback** — use when you need custom type coercion, formula injection, or the CSV lives inside another data pipeline. Recipe for 600-6000+ cells:\n\n```python\n# gen_batch.py — produces batch chunks of 80 value-set ops each\nimport csv, json\nops = []\nwith open(\"data.csv\") as f:\n    reader = csv.reader(f)\n    for r, row in enumerate(reader, start=1):\n        for c, val in enumerate(row):\n            col = chr(ord('A') + c)\n            ops.append({\"command\":\"set\",\"path\":f\"\u002FData\u002F{col}{r}\",\n                        \"props\":{\"value\": val}})\nfor i in range(0, len(ops), 80):\n    print(json.dumps(ops[i:i+80]))\n```\n\n```bash\npython gen_batch.py | while IFS= read -r chunk; do\n  printf '%s\\n' \"$chunk\" | officecli batch \"$FILE\"\ndone\n```\n\nOutcome: 648-row retail CSV (6490 cells) loads in ~30s, zero failures. Tune: start at 80 ops\u002Fchunk, drop to 40 if any chunk fails. Numeric type inference and formulas come later via targeted `set` — batch in this recipe is pure value injection.\n\n## Reading & Analysis\n\nStart wide, then narrow. `outline` first tells you what sheets exist and where the data is; jump into `view` \u002F `get` \u002F `query` only once you know where to look.\n\n**Open the rendered workbook to eyeball your own work.**\n- `officecli view $FILE html` — Read the returned HTML to audit the rendered output. Each sheet is addressable, charts render inline. Catches `###`, placeholder leakage, pivot layout, row-height clipping.\n- `officecli watch $FILE` keeps a live preview running for the human user — they open it at their own discretion. Use when the user wants to watch along; agent self-check uses `view html` above.\nUse `view html` as your **first visual check after a batch of edits** — fix at source. For final visual verification, the user opens the `.xlsx` in their Excel \u002F WPS \u002F Numbers viewer.\n\n**Orient.** Sheets, dimensions, formula counts.\n\n```bash\nofficecli view \"$FILE\" outline\n```\n\n**Extract.** Plain text dump for content QA or LLM context; scope with `--start` \u002F `--end` \u002F `--cols` for big files.\n\n```bash\nofficecli view \"$FILE\" text --start 1 --end 50 --cols A,B,C\n```\n\nOther `view` modes worth knowing: `annotated` (cell values + types\u002Fformulas + warnings), `stats` (numeric summaries), `issues` (broken formulas, empty sheets, missing refs).\n\n**Inspect one element.** Use XPath-style paths. Always quote — shells glob `[N]`.\n\n```bash\nofficecli get \"$FILE\" \"\u002FSheet1\u002FA1\"            # one cell\nofficecli get \"$FILE\" \"\u002FSheet1\u002FA1:D10\"        # range\nofficecli get \"$FILE\" \"\u002FSheet1\u002Fchart[1]\"      # chart\nofficecli get \"$FILE\" \"\u002FSheet1\u002Ftable[1]\"      # ListObject\nofficecli get \"$FILE\" \"\u002Fnamedrange[1]\"        # workbook-level named range\n```\n\nAdd `--depth N` to expand children; add `--json` for machine output. Full element list: `officecli help xlsx`.\n\n**Query across the workbook.** CSS-like selectors. Use for systematic checks (formula coverage, error cells, empty headers) rather than hand-walking.\n\n```bash\nofficecli query \"$FILE\" 'cell:has(formula)'       # every formula cell\nofficecli query \"$FILE\" 'cell:contains(\"#REF!\")'  # broken references\nofficecli query \"$FILE\" 'cell[type=Number]'       # typed filter\nofficecli query \"$FILE\" 'Sheet1!B[value!=0]'      # sheet-scoped\n```\n\nOperators: `=`, `!=`, `~=` (contains), `>=`, `\u003C=`, `[attr]` (exists).\n\n**Merge cells shortcut.** `officecli query $FILE merge` or `mergedrange` — both are aliases for `mergeCell` (1.0.60+). Returns every merged range in the workbook without hand-walking `\u003CmergeCell>` entries.\n\n**When the data is big enough that a row-walk is useless**, reach for Excel's own analytical elements:\n\n- Build a **pivot table** with `officecli add` (`--type pivottable`) to group\u002Faggregate without writing 20 SUMIFs. Attach a **slicer** (`--type slicer`) to give the reader a filter UI.\n- Drop a **sparkline** (`--type sparkline`) in a row to show per-row trends — cheaper than one line chart per row and they print inline. `type` is a strict enum: **`line | column | stacked`** (plus aliases `winloss` \u002F `win-loss` → `stacked`). Invalid `type=` values hard-fail on 1.0.58+ — no silent fallback to `line` anymore.\n- Run `officecli help xlsx pivottable`, `officecli help xlsx slicer`, `officecli help xlsx sparkline` for the exact prop names.\n\n## Creating & Editing\n\nNinety percent of a build is cells, formulas, formatting, and one or two charts. The verbs: `add` (new element), `set` (change a prop), `remove`, `move`, `swap`, `batch`.\n\n### Cells and formulas\n\nSet a value and its format in one call. Never write `=` at the start of a formula — the CLI strips it.\n\n```bash\nofficecli set \"$FILE\" \u002FSheet1\u002FB5 --prop formula=\"SUM(B2:B4)\" --prop numFmt='$#,##0'\nofficecli set \"$FILE\" \u002FSheet1\u002FC5 --prop formula=\"B5\u002FA5\" --prop numFmt=\"0.0%\"\n```\n\nStructural properties (width, height, freeze, tabColor) live on row \u002F col \u002F sheet nodes:\n\n```bash\nofficecli set \"$FILE\" \"\u002FSheet1\u002Fcol[A]\" --prop width=20\nofficecli set \"$FILE\" \"\u002FSheet1\u002Frow[1]\" --prop height=22\nofficecli set \"$FILE\" \"\u002FSheet1\" --prop freeze=A2 --prop tabColor=1F4E79\n```\n\n### Named ranges\n\nPrefer named ranges over `$B$6` in formulas. They self-document (`GrowthRate` beats `$B$6`) and they let you move the assumption cell without breaking formulas. Because `ref` values contain both `!` and `$`, add them through a batch heredoc:\n\n```bash\ncat \u003C\u003C'EOF' | officecli batch \"$FILE\"\n[\n  {\"command\":\"add\",\"parent\":\"\u002F\",\"type\":\"namedrange\",\"props\":{\"name\":\"GrowthRate\",\"ref\":\"Sheet1!$B$6\"}}\n]\nEOF\n```\n\nSee `officecli help xlsx namedrange` for the full schema.\n\n**Batch JSON does NOT accept shell aliases.** Inside batch `props`, always use the full dotted name — `\"font.color\": \"FF0000\"`, `\"font.size\": 14`, never `\"color\": \"FF0000\"` (ambiguous: text vs fill). On a bare cell, even the shell form is rejected: `--prop color=1F4E79` errors with `ambiguous in cell context — use 'font.color' (text) or 'fill' (bg)`. Rule: in any batch JSON or cell prop, write `font.color` \u002F `fill` explicitly. `parent` should be `\"\u002F\"` for workbook-level elements and `\"\u002FSheetName\"` for sheet-scoped; empty string is not equivalent.\n\n### Charts\n\nChart types live under `officecli help xlsx chart` — the enum is long (20+). Pick the right one for the message: column for category comparison, line for time series, pie only when slices are self-evidently proportional, scatter for correlation. Avoid exotic types unless they answer a specific question.\n\n**Three ways to feed chart data. Pick one per chart — mixing them at add-time is a common trap.**\n\n| Form | Shape | When to use |\n|---|---|---|\n| (a) inline `data` | `--prop data=\"Sales:100,200,300\" --prop categories=\"Jan,Feb,Mar\"` | Tiny demo charts, numbers you will not edit. Source of truth lives in the chart XML, not a cell. |\n| (b) 2D `dataRange` | `--prop dataRange=\"Sheet1!A1:B4\"` (first col = categories, first row = header \u002F series name) | Normal case. Must be **2-D** — single column fails with \"Chart requires data\". |\n| (c) dotted per-series | `--prop series1.name=Sales --prop series1.values=\"Sheet1!B2:B4\" --prop series1.categories=\"Sheet1!A2:A4\"` | Multi-series charts where each series points at non-contiguous ranges, or you want explicit series naming. `series1.values` alone (no `categories`) emits a chart with `1,2,3` as the x-axis. |\n\n**The single-column trap.** `dataRange=\"Sheet1!B2:B13\"` looks like \"value column\" but the engine rejects it with `Chart requires data`. Either widen the range to include the category column (`A2:B13`), or switch to form (c) with explicit `series1.categories`.\n\n**Chart `anchor` and series are immutable after create.** `set chart[N] --prop anchor=...` is rejected (`UNSUPPORTED props: anchor`); likewise new series cannot be appended. To resize, move, or add a series: `officecli remove` the chart, then `officecli add` with the new anchor \u002F full series list. Also note: `remove chart[1]` shifts `chart[2] → chart[1]`, and re-add **appends at the end** — to preserve chart order, remove all and rebuild in order.\n\n**Anchor sizing.** No auto-fit. A column chart with 5-6 categories + 2 series needs roughly `A5:L22` (12 cols × 18 rows) to show all labels uncut. Narrower and X-axis labels clip; wider and the chart can split across pages on print\u002Fexport. If in doubt, start narrow, preview via `view html` (Read the returned HTML path), widen in increments. Page layout (below) is the other half of the fix.\n\n**Chart `dataRange` — always prefix with the sheet.** Even when the chart lives on the same sheet, write `dataRange=\"Summary!A17:C22\"`, not `A17:C22`. The sheet-less form works inconsistently; the prefixed form is 100% reliable.\n\nofficecli adds extended chart types the classic Excel object model lacks: `boxWhisker`, `waterfall`, `funnel`, `histogram`, `treemap`, `sunburst`. Use them when the data calls for them. Known-bad: `chartType=pareto` (produces invalid XML — use `column` or `boxWhisker`).\n\n**NEVER put unreplaced template tokens in chart title \u002F series name \u002F legend \u002F axis title.** `$fy$24`, `{var}`, `\u003CTODO>`, `$VAR`, `{{placeholder}}` render **literally** in the legend — validate passes, but a CFO sees `$fy$24` where \"FY2024\" should be. Always bind to final text or a cell reference (`title=\"FY2024 Revenue\"` or `series1.name=\"Sheet1!A1\"`).\n\n### Conditional formatting\n\nThree common flavors, each with its own prop shape (consult `officecli help xlsx cf`):\n\n- **Color scales**: cells shaded on a gradient by value — `type=colorscale` with `minColor` \u002F `midColor` \u002F `maxColor`.\n- **Data bars**: in-cell bars showing magnitude — `type=databar`. ALWAYS set explicit `min` and `max`; defaults emit invalid XML (see Known Issues).\n- **Formula rules**: highlight row when a condition is true — `type=formulacf` with `formula=\"$C2>1000\"` and a fill\u002Ffont.\n\nRule: apply CF sparingly. A workbook where every cell is colored tells the reader nothing.\n\n### Data validation\n\nInput cells in trackers and templates MUST carry data validation. It's cheap and it stops entire classes of downstream bugs. **Three list-source patterns** — pick based on where the allowed values live.\n\n**(a) Inline list** — allowed values are short and fixed in the rule itself.\n\n```bash\nofficecli add \"$FILE\" \u002FSheet1 --type validation \\\n  --prop sqref=\"C2:C100\" --prop type=list \\\n  --prop formula1=\"Yes,No,Maybe\" \\\n  --prop showError=true --prop errorTitle=\"Invalid\" --prop error=\"Select from list\"\n```\n\n**(b) Named range (preferred for cross-sheet lookups)** — allowed values live in another sheet and may grow. Define the named range first, then reference it. Use a batch heredoc because `ref` contains `!` and `$`:\n\n```bash\ncat \u003C\u003C'EOF' | officecli batch \"$FILE\"\n[\n  {\"command\":\"add\",\"parent\":\"\u002F\",\"type\":\"namedrange\",\"props\":{\"name\":\"StatusList\",\"ref\":\"Lookups!$A$2:$A$4\"}},\n  {\"command\":\"add\",\"parent\":\"\u002FSheet1\",\"type\":\"validation\",\"props\":{\"sqref\":\"B2:B100\",\"type\":\"list\",\"formula1\":\"=StatusList\"}}\n]\nEOF\n```\n\n**(c) Direct cross-sheet range** — no named range, raw `Lookups!$A$2:$A$4` inside `formula1`. Also needs a batch heredoc to keep `!` and `$` intact:\n\n```bash\ncat \u003C\u003C'EOF' | officecli batch \"$FILE\"\n[\n  {\"command\":\"add\",\"parent\":\"\u002FSheet1\",\"type\":\"validation\",\"props\":{\"sqref\":\"C2:C100\",\"type\":\"list\",\"formula1\":\"Lookups!$A$2:$A$4\"}}\n]\nEOF\n```\n\nIf you write the cross-sheet variant as `--prop formula1=...` on the shell, the `!` gets shell-mangled into `\\!` and the dropdown will silently fall back to no list. Verify with `officecli get \"$FILE\" \u002FSheet1\u002Fvalidation[N]` — `formula1=` must show a plain `!`, no backslash.\n\nOther common `type` values: `decimal`, `whole`, `date`, `textLength`, `custom`. See `officecli help xlsx validation` for operators and the full prop list.\n\n### Other elements (one-liners)\n\n- **Tables** (ListObjects) — `add --type table` with a range; gives auto-filter + structured refs. `officecli help xlsx table`.\n- **Comments** — `add --type comment`; use for documenting hardcoded assumptions. `officecli help xlsx comment`.\n- **Sheet reordering** — `officecli move`, not `swap`. `swap` only works on row\u002Fcell paths.\n\n## Chart Axis-by-Role\n\nEditing a chart axis in place is cheaper than rebuilding the chart. Address axes by **role** (`value` = Y, `category` = X), not by index — the XML order isn't stable.\n\n```bash\nofficecli get \"$FILE\" \"\u002FSheet1\u002Fchart[1]\u002Faxis[@role=value]\"\nofficecli set \"$FILE\" \"\u002FSheet1\u002Fchart[1]\u002Faxis[@role=value]\" --prop min=0 --prop max=100000\nofficecli set \"$FILE\" \"\u002FSheet1\u002Fchart[1]\u002Faxis[@role=category]\" --prop title=\"Month\"\n```\n\nSafe props: `title`, `min`, `max`, `majorGridlines`, `visible`. Do NOT use `labelRotation` — it emits invalid XML today (see Known Issues).\n\n## QA (Required)\n\n**Assume there are problems. Your job is to find them.**\n\nYour first workbook is almost never correct. Treat QA as a bug hunt, not a confirmation step. If you found zero issues on first inspection, you were not looking hard enough. The formulas look fine **until** you check two of them against source cells.\n\n### Minimum cycle before \"done\"\n\n1. `officecli view \"$FILE\" issues` — empty sheets, broken formulas, missing refs.\n2. `officecli view \"$FILE\" annotated` (sample ranges) — values + types + warnings.\n3. For every Excel error type, query it:\n   ```bash\n   officecli query \"$FILE\" 'cell:contains(\"#REF!\")'\n   officecli query \"$FILE\" 'cell:contains(\"#DIV\u002F0!\")'\n   officecli query \"$FILE\" 'cell:contains(\"#VALUE!\")'\n   officecli query \"$FILE\" 'cell:contains(\"#NAME?\")'\n   officecli query \"$FILE\" 'cell:contains(\"#N\u002FA\")'\n   ```\n4. `officecli validate \"$FILE\"` — close any resident first (see Known Issues).\n5. **Visual pass — walk every sheet via the HTML preview.** Run `officecli view \"$FILE\" html` and Read the returned HTML path. Each sheet renders with charts inline. Scan for `###`, truncated titles, placeholder tokens (`$fy$24`, `{var}`, `\u003CTODO>`), sliced charts, white-slice pie charts, empty chart anchors — **STOP and fix before declaring done**. \"validate pass\" is not delivery; \"the preview looks like a real workbook\" is delivery. For human preview, run `officecli watch \"$FILE\"` (user opens the live preview at their own discretion) or have them open the `.xlsx` directly in Excel \u002F WPS \u002F Numbers.\n6. **Print layout fix (wide tables \u002F multi-chart sheets).** When a sheet holds a chart or a wide table and the user will print it, set per-sheet page layout so it fits on one page:\n   ```bash\n   officecli set \"$FILE\" \"\u002FSummary\" --prop orientation=landscape --prop fitToPage=true\n   ```\n   Outcome: each sheet's print layout is one page with no mid-chart splits. Apply to every sheet that holds a chart or a > 8-column table.\n7. If anything failed, fix, then **rerun the full cycle**. One fix commonly creates another problem.\n\n`officecli view issues` + `view html` are the structural QA pair: `issues` catches broken formulas and empty sheets; `view html` (Read the returned HTML path) catches `###`, truncation, and token leakage. Chart fill colors \u002F theme tints can vary across viewers — spot-check in the user's target viewer when color fidelity matters.\n\n### Formula verification checklist\n\n- [ ] Pick 2-3 formulas at random. Run `officecli get` on each. Confirm the formula string is what you intended **and** `cachedValue=` is what you expect — arithmetic in your head.\n- [ ] **Cached value sanity on every summary cell.** Any cell that aggregates (COUNTA \u002F COUNTIF \u002F SUMPRODUCT \u002F INDEX&MATCH) must have a plausible `cachedValue`. If a progress tracker shows `199 \u002F 199 \u002F 100%` on a blank template, the cache is lying — re-touch the formula via `set` (forces recompute) or manually set a correct cached value. Do NOT ship \"validate passes but the numbers are fiction\".\n- [ ] **Spot-check one cell per numeric column.** `%` columns showing integer `0.0%` throughout means the denominator is wrong or the numerator is cached stale — investigate one cell, fix the pattern.\n- [ ] Ranges include every row: off-by-one on `SUM(B2:B12)` when data goes to `B13` is the most common bug.\n- [ ] Cross-sheet formulas (`Sheet1!A1`) contain no `\\!`. If `officecli get` shows `Sheet1\\!A1`, the `!` was shell-corrupted — delete and re-enter via batch\u002Fheredoc.\n- [ ] Named ranges (`officecli get \"$FILE\" \"\u002Fnamedrange[1]\"`) point at what their names claim.\n- [ ] Every `\u002F` denominator is guarded — `IFERROR(x\u002Fy, 0)` or `IF(y=0, 0, x\u002Fy)`.\n- [ ] Chart data vs source cells: for every chart with inline data, spot-check data points against `officecli get` of the source cells.\n- [ ] Chart title \u002F series name \u002F legend contain **no** unreplaced tokens (`$...$`, `{var}`, `\u003CTODO>`). Grep the chart via `officecli get \u002FSheet1\u002Fchart[N]`.\n\n### Template QA\n\nWhen editing a template, check for leftover placeholders — they look like content and slip past `validate`:\n\n```bash\nofficecli query \"$FILE\" 'cell:contains(\"{{\")'\nofficecli query \"$FILE\" 'cell:contains(\"xxxx\")'\nofficecli query \"$FILE\" 'cell:contains(\"TBD\")'\n```\n\n### Fresh eyes\n\nWhen you finish a workbook, open it fresh. Read `view text` \u002F HTML preview top-to-bottom as if you are a new reviewer — look for formulas, numbers that look off, formatting inconsistency, missing data.\n\n### Honest limit\n\n`validate` catches schema errors, not design errors. A workbook can pass `validate` with every number wrong. The checklist above — especially spot-checking formulas against source cells — is how you catch what validation can't.\n\n## Known Issues & Pitfalls\n\n### The cross-sheet `!` trap (short)\n\nShells (bash history expansion, zsh splitting) and CLI arg parsing mangle `!` in `Sheet1!A1` into `\\!`. A formula containing `\\!` is silently broken — it renders as literal text and references nothing.\n\n**Fix.** Use a batch heredoc with single-quoted delimiter (`\u003C\u003C'EOF'`), which disables all shell expansion:\n\n```bash\ncat \u003C\u003C'EOF' | officecli batch \"$FILE\"\n[{\"command\":\"set\",\"path\":\"\u002FSummary\u002FB2\",\"props\":{\"formula\":\"Revenue!B13\"}}]\nEOF\n```\n\n**Verify.** After writing, `officecli get` the cell; `formula=` must show a plain `!` with no backslash.\n\n### CLI bug backlog (short)\n\nAvoid these until fixed; they produce invalid XML or silent breakage.\n\n- **`chartType=pareto`** — emits empty `cx:axisId val=\"\"`; `validate` fails after `close`. Substitute `column` or `boxWhisker`.\n- **`labelRotation` on axis-by-role** — inserts bad `a:endParaRPr`. Use `title`\u002F`min`\u002F`max`\u002F`majorGridlines`\u002F`visible` only.\n- **Data bar without explicit min\u002Fmax** — default cfvo `val=\"\"` is invalid. Always pass `--prop min=N --prop max=N`.\n- **Chart `anchor` and series are immutable after create** — to resize\u002Fmove\u002Fadd-series: `remove` + `add`. `remove chart[N]` shifts subsequent indices down; re-add appends at end.\n- **`validate` while resident open** — reports spurious `tableParts` \u002F `drawing` errors. Always `close` first.\n- **Batch + resident for formulas — avoid.** Observed deadlocks (CPU 99%, `main pipe busy`, kill -9 required) for cross-sheet formula batches even at 3-5 ops; the prior \"≤ 12 ops safe\" guideline is **not reliable**. Rule: **cross-sheet formulas go through non-resident one-big-batch OR individual `set`** (100% reliable). Pure value-set batches (no formulas) stay reliable at 50-80+ ops even in resident. **Multiple officecli resident processes on the same machine also contend** — if another agent\u002Fsession is running resident, expect non-deterministic hangs.\n- **Conditional formatting naming asymmetry** — the element name for `--type` is `conditionalformatting`; the path suffix is `\u002Fcf[N]`. Use `officecli help xlsx conditionalformatting` for schema, `\u002Fcf[N]` for paths.\n- **Sheet `position` prop on add** — help says Add processes `position`, but the prop is often ignored. Reorder with `officecli move --index` \u002F `--after` \u002F `--before` after creating the sheet.\n- **`remove \u002Fsheet[N]` cascade guard** — 1.0.59+ rejects sheet remove\u002Frename when the sheet is referenced by validation \u002F conditional format \u002F sparkline \u002F hyperlink \u002F named range on another sheet. Remove those dependent elements first, then remove the sheet.\n- **Batch JSON rejects cell `color` alias** — inside batch `props`, `\"color\": \"FF0000\"` errors `ambiguous in cell context — use 'font.color' (text) or 'fill' (bg)`. The CLI at shell level accepts `--prop color=...` \u002F `--prop size=14` as aliases on non-cell elements, but inside batch JSON on a cell always write the full dotted name: `\"font.color\"`, `\"font.size\"`, `\"font.name\"`.\n- **`SUMPRODUCT((range=criterion)*values)` caches `0` on 1.0.63** — the CLI calc engine does not evaluate array-predicate `SUMPRODUCT` at write-time; runtime Excel\u002FWPS compute fine but the cached `0` ships to non-recalculating readers. **Helper-column fallback:** add a column `F` on the source sheet with `=C2*D2` per row, then aggregate via `=SUMIF(B:B, \"Region X\", F:F)`. Caches correctly, audits cleanly, and survives non-recalculating viewers.\n\n### Renderer caveats (cross-viewer color fidelity)\n\n`officecli view html` is the right tool for structural QA (overflow, truncation, placeholder leakage, layout) — Read the returned HTML path. Some chart rendering details vary across the viewer the end user opens the file in. Observed divergences:\n\n- **Pie \u002F doughnut fill colors may collapse to a single theme tint** in some viewers (slices look \"all white\" or \"all one color\"). The file may be fine in the user's target viewer.\n- **Line chart \u002F column chart series colors may drift** from the workbook theme in some viewers.\n- **Form-control checkboxes may render as double-boxed** in some viewers.\n\nBefore calling a color or chart \"broken\", open the file in the user's actual target viewer. If it looks correct there, the problem is viewer rendering, not data — do not chase it. The CLI's structural checks (`###`, truncation, placeholder text, layout) remain authoritative.\n\n### Escape layers (shell quoting is above; these are the extras)\n\nThe CLI does not interpret `\\$` \u002F `\\t` \u002F `\\n` — they land as literal characters. Shell-level rules are in L25-30. Two additional layers:\n\n- **JSON level (batch).** Standard JSON escapes — `\"\\n\"`, `\"\\t\"`, `\"\\\"\"`. A real backslash in the final string is `\"\\\\\\\\\"`.\n- **Excel level.** `\\n` in a cell for line break → write `\"\\n\"` **inside JSON**. In a shell-quoted prop it stays literal (Excel shows `\\n` text). When in doubt, `officecli get` the cell and compare character-for-character.\n\n### Other common pitfalls\n\n| Pitfall | Fix |\n|---|---|\n| `--name \"foo\"` | All attrs go through `--prop`: `--prop name=\"foo\"` |\n| Guessing a prop name | `officecli help xlsx \u003Celement>` — don't improvise |\n| `--prop color=...` on a cell | Ambiguous — use `font.color` (text) or `fill` (bg). Also applies inside batch JSON: always use full dotted names, never shell aliases |\n| `#FF0000` hex colors | Drop the `#`: `FF0000` |\n| `--index` vs `[N]` | `--index` is 0-based (array); `[N]` paths are 1-based (XPath) |\n| Unquoted `[N]` in zsh\u002Fbash | Quote every path: `\"\u002FSheet1\u002Frow[1]\"` |\n| Sheet name with spaces | Quote full path: `\"\u002FMy Sheet\u002FA1\"` |\n| Year showing as `2,026` | `--prop type=string` or `numFmt=\"@\"` |\n| Modifying a file open in Excel | Close it in Excel first |\n| `swap` not reordering sheets | `swap` is for rows\u002Fcells. Use `move --after` \u002F `--before` \u002F `--index` for sheets |\n| Cached values missing after write | New formulas get cached values when a human opens the file; `validate` accepts them either way |\n","# OfficeCLI XLSX Skill\n\n## Setup\n\nIf `officecli` is missing:\n\n- **macOS \u002F Linux**: `curl -fsSL https:\u002F\u002Fd.officecli.ai\u002Finstall.sh | bash`\n- **Windows (PowerShell)**: `irm https:\u002F\u002Fd.officecli.ai\u002Finstall.ps1 | iex`\n\nVerify with `officecli --version` (open a new terminal if PATH hasn't picked up). If install fails, download a binary from https:\u002F\u002Fgithub.com\u002FiOfficeAI\u002FOfficeCLI\u002Freleases.\n\n## ⚠️ Help-First Rule\n\n**This skill teaches what good xlsx looks like, not every command flag. When a property name, enum value, or alias is uncertain, consult help BEFORE guessing.**\n\n```bash\nofficecli help xlsx                         # List all xlsx elements\nofficecli help xlsx \u003Celement>               # Full element schema (e.g. pivottable, chart, cf)\nofficecli help xlsx \u003Cverb> \u003Celement>        # Verb-scoped (e.g. add chart, set cell)\nofficecli help xlsx \u003Celement> --json        # Machine-readable schema\n```\n\nHelp reflects the installed CLI version. When this skill and help disagree, **help is authoritative**.\n\n## Shell & Execution Discipline\n\n**Shell quoting (zsh \u002F bash).** Excel paths contain `[]`, and number formats contain `$`. Both are shell metacharacters. Rules:\n\n- ALWAYS quote element paths: `\"\u002FSheet1\u002Frow[1]\"`, not `\u002FSheet1\u002Frow[1]`.\n- Use **single quotes** for any prop value containing `$`: `numFmt='$#,##0'`.\n- For formulas with cross-sheet `!` references, use `batch` with a `\u003C\u003C'EOF'` heredoc (see Known Issues).\n- NEVER hand-write `\\$`, `\\t`, `\\n` inside executable examples. The CLI does not interpret backslash escapes; they will land in your file as literal characters.\n\n**Incremental execution.** Run commands one at a time and read each exit code. `officecli` mutates the file on every call; a 50-command script that fails at command 3 will cascade silently. One command → check output → continue.\n\n## Requirements for Outputs\n\nBefore reaching for a command, know what a good xlsx looks like. These are the deliverable standards every workbook MUST meet.\n\n### All Excel files\n\n**Zero formula errors.** Every delivered workbook MUST have ZERO `#REF!`, `#DIV\u002F0!`, `#VALUE!`, `#NAME?`, `#N\u002FA`. No exceptions — guard denominators with `IFERROR` or `IF(x=0,...)`.\n\n**Formulas, not hardcoded values.** If a number can be computed from other cells, it is a formula. Hardcoding `5000` where `=SUM(B2:B9)` belongs breaks the contract that the workbook stays live when inputs change. This is the single most important rule in this skill.\n\n**Professional font.** Use one consistent, professional font across the workbook (Arial \u002F Calibri \u002F Times New Roman). Don't mix four fonts because one sheet came from CSV.\n\n**Explicit widths.** There is no auto-fit. Any column the user will read MUST have `width` set — default 8.43 chars clips everything. Sensible starts: labels 20-25, numbers 12-15, dates 12, short codes 8-10.\n\n**Preserve existing templates.** When editing a file that already has a look, match it. Existing conventions override these guidelines.\n\n### Visual delivery floor (applies to EVERY workbook)\n\nBefore you declare done, run `officecli view \"$FILE\" html` and Read the returned HTML path to confirm all of these:\n\n- **No `###` in any cell.** `###` means a column is too narrow for its widest value. Every column the user reads needs an explicit `width`. `###` in a delivered file is unfinished work, never \"a small visual nit\".\n- **No truncated titles.** Sheet titles, section headers, long labels must fit. Widen the column or apply `wrapText=true` on the cell.\n- **No placeholder tokens rendered as data.** `$fy$24`, `{var}`, `\u003CTODO>`, `xxxx` must never appear in a cell, chart title, series name, or legend. These are build-time tokens that escaped replacement.\n- **Pie \u002F doughnut slices have distinct fill colors.** If the slices render same-colored, switch to `bar` \u002F `column` or set `colors=...` explicitly.\n- **No empty trailing pages \u002F empty chart anchors.** `anchor=D2:J18` over empty source cells looks like a broken chart.\n\nIf any of the above fails, STOP and fix before declaring done.\n\n**Print layout.** Any sheet the user may print or send as a board pack needs page setup. Default portrait + no fit-to-page splits wide tables and charts mid-way. Apply per sheet:\n\n```bash\nofficecli set \"$FILE\" \"\u002FSummary\" --prop orientation=landscape --prop fitToPage=true\n```\n\nTrigger: sheet holds a chart, or > 8 columns, or the user's ask mentions print \u002F board \u002F investor.\n\n### Financial models only — skip this section if you are building a template, tracker, CSV import, or operational sheet\n\nScope: budgets, forecasts, 3-statement models, valuation, any `$`-heavy analytical workbook. A customer-support tracker or onboarding template does not need this section.\n\n**Color coding — industry standard.** Five core colors used as a language, not decoration. A reviewer should tell what a cell IS by color alone — before reading the formula.\n\n| Color | Role | Example |\n|---|---|---|\n| Blue text `0000FF` | Hardcoded inputs, scenario variables | `font.color=0000FF` |\n| Black text `000000` | ALL formulas and calculations | default |\n| Green text `008000` | Cross-sheet links inside this workbook | `font.color=008000` |\n| Red text `FF0000` | Links to external files \u002F workbooks | `font.color=FF0000` |\n| Yellow fill `FFFF00` | Key assumptions needing review | `fill=FFFF00` |\n\nA reviewer should tell what a cell IS just by its color — before reading the formula. This is a communication contract, not a cosmetic preference.\n\n**Number formatting — standards, not preferences.**\n\n- **Years** are text, not numbers. Format `2026` not `2,026` — use `numFmt=\"@\"` or set `type=string`.\n- **Currency** carries its unit in the header (`Revenue ($mm)`), not in every cell.\n- **Zeros display as `-`**, not `0`. Use `$#,##0;($#,##0);\"-\"`.\n- **Percentages** default to one decimal: `0.0%`.\n- **Negatives use parentheses**: `(1,234)` not `-1,234`.\n- **Valuation multiples** use `0.0x` format (EV\u002FEBITDA, P\u002FE, etc.).\n\n**Assumptions live in cells, not inside formulas.** `=B5*(1+$B$6)` is correct; `=B5*1.05` is a bug. Document each blue hardcoded input with an adjacent source note in the next cell or a cell comment:\n\n```\nSource: Company 10-K, FY2024, Page 45, Revenue Note\nSource: Bloomberg, 2026-05-02, AAPL US Equity\nSource: Management guidance, Q2 2026 earnings call\n```\n\nAny hardcoded number without a source is an undocumented assumption — a reviewer cannot audit it.\n\n## Common Workflow\n\nSix steps. Every non-trivial build follows this shape.\n\n1. **Choose the mode.** Always use `officecli open \u003Cfile>` at the start and `officecli close \u003Cfile>` at the end. Resident mode is the default, not an optimization — it avoids re-parsing the file on every command. For many cells, use `batch`: **≤ 50 ops\u002Fblock recommended; tested up to 80+ ops per block on pure value-set payloads with zero failures. Cross-sheet formula batches are the exception — run those non-resident, single heredoc (see Known Issues)**.\n2. **Create or load.** `officecli create \"$FILE\"` (new) or `officecli view \"$FILE\" outline` (existing — get the lay of the land first).\n3. **Build incrementally.** One command, read the output, continue. After any structural op (new sheet, chart, named range, pivot), run `get` on it to confirm shape before stacking more on top.\n4. **Format.** Column widths, number formats, freeze panes, tab colors, header fills. Formatting is not optional polish — per \"Requirements for Outputs\" it is part of the deliverable.\n5. **Close, then reckon with the cache.** `officecli close \u003Cfile>` writes to disk. Newly-added formulas ship without cached values; when a human opens the file in a spreadsheet app, the app recalculates and populates them. **But your downstream `INDEX\u002FMATCH`, `SUMPRODUCT`, or any formula that references an upstream formula will cache whatever the upstream cached at write-time — often `0` or a stale value — and that cached lie survives into non-recalculating readers.** After any multi-formula build involving array formulas (`SUMPRODUCT`, `SUMIFS` with dynamic criteria) or cross-sheet chains, **re-touch every downstream cell** (run `set` again with the same formula) so the engine recomputes its cache from the freshly-cached upstream. ⚠️ Re-touch on cross-sheet chains via resident is unreliable (see Batch \u002F resident caveats) — prefer non-resident `set` for the re-touch pass. Then `officecli get` a few downstream cells and eyeball that their `cachedValue=` is plausible. **Array-formula fallback:** for `SUMPRODUCT(1\u002FCOUNTIF(range, range))` distinct-count patterns, the CLI engine treats the inner division as scalar and caches `1\u002FN` (e.g. `0.001543`) rather than the true distinct count. Re-touching won't fix it. **Fallback: hardcode the correct value + an adjacent comment `\"hardcoded distinct count; update if Data rows change\"`, and tell the reader at delivery**. Better than shipping a cached lie. Do NOT run `validate` while a resident is open — it reports spurious drawing errors.\n6. **QA — assume there are problems.** See the QA section. You are not done when your last command exited 0; you are done after one fix-and-verify cycle finds zero new issues.\n\n## Quick Start\n\nMinimal viable xlsx: 3 months of revenue + a total formula + column widths + a currency format. Adapt, don't copy-paste — your file, your data.\n\n```bash\nofficecli create \"$FILE\"\nofficecli open \"$FILE\"\nofficecli set \"$FILE\" \u002FSheet1\u002FA1 --prop value=Month --prop bold=true\nofficecli set \"$FILE\" \u002FSheet1\u002FB1 --prop value=Revenue --prop bold=true\nofficecli set \"$FILE\" \u002FSheet1\u002FA2 --prop value=Jan\nofficecli set \"$FILE\" \u002FSheet1\u002FA3 --prop value=Feb\nofficecli set \"$FILE\" \u002FSheet1\u002FA4 --prop value=Mar\nofficecli set \"$FILE\" \u002FSheet1\u002FB2 --prop value=42000 --prop numFmt='$#,##0'\nofficecli set \"$FILE\" \u002FSheet1\u002FB3 --prop value=45000 --prop numFmt='$#,##0'\nofficecli set \"$FILE\" \u002FSheet1\u002FB4 --prop value=48000 --prop numFmt='$#,##0'\nofficecli set \"$FILE\" \u002FSheet1\u002FA5 --prop value=Total --prop bold=true\nofficecli set \"$FILE\" \u002FSheet1\u002FB5 --prop formula=\"SUM(B2:B4)\" --prop bold=true --prop numFmt='$#,##0'\nofficecli set \"$FILE\" \"\u002FSheet1\u002Fcol[A]\" --prop width=12\nofficecli set \"$FILE\" \"\u002FSheet1\u002Fcol[B]\" --prop width=15\nofficecli close \"$FILE\"\nofficecli validate \"$FILE\"\n```\n\nVerified: `validate` returns `no errors found`, `B5` resolves to `135000`. This is the shape of every build: open → set cells\u002Fformulas → format → close → validate.\n\n## CSV \u002F bulk import\n\n**Native `import` command (preferred for CSV\u002FTSV).** Fastest path; loads a CSV into a sheet in one call. `--header` sets AutoFilter + freeze pane on row 1. Widths and `numFmt` still need a follow-up pass (per D-12 in Dashboard skill).\n\n```bash\nofficecli import \"$FILE\" \u002FSheet1 --file data.csv --header\nofficecli import \"$FILE\" \u002FSheet1 --file data.tsv --format tsv --header\nofficecli import \"$FILE\" \u002FSheet1 --stdin --start-cell B2 \u003C data.csv\n```\n\n**Python + batch fallback** — use when you need custom type coercion, formula injection, or the CSV lives inside another data pipeline. Recipe for 600-6000+ cells:\n\n```python\n# gen_batch.py — produces batch chunks of 80 value-set ops each\nimport csv, json\nops = []\nwith open(\"data.csv\") as f:\n    reader = csv.reader(f)\n    for r, row in enumerate(reader, start=1):\n        for c, val in enumerate(row):\n            col = chr(ord('A') + c)\n            ops.append({\"command\":\"set\",\"path\":f\"\u002FData\u002F{col}{r}\",\n                        \"props\":{\"value\": val}})\nfor i in range(0, len(ops), 80):\n    print(json.dumps(ops[i:i+80]))\n```\n\n```bash\npython gen_batch.py | while IFS= read -r chunk; do\n  printf '%s\\n' \"$chunk\" | officecli batch \"$FILE\"\ndone\n```\n\nOutcome: 648-row retail CSV (6490 cells) loads in ~30s, zero failures. Tune: start at 80 ops\u002Fchunk, drop to 40 if any chunk fails. Numeric type inference and formulas come later via targeted `set` — batch in this recipe is pure value injection.\n\n## Reading & Analysis\n\nStart wide, then narrow. `outline` first tells you what sheets exist and where the data is; jump into `view` \u002F `get` \u002F `query` only once you know where to look.\n\n**Open the rendered workbook to eyeball your own work.**\n- `officecli view $FILE html` — Read the returned HTML to audit the rendered output. Each sheet is addressable, charts render inline. Catches `###`, placeholder leakage, pivot layout, row-height clipping.\n- `officecli watch $FILE` keeps a live preview running for the human user — they open it at their own discretion. Use when the user wants to watch along; agent self-check uses `view html` above.\nUse `view html` as your **first visual check after a batch of edits** — fix at source. For final visual verification, the user opens the `.xlsx` in their Excel \u002F WPS \u002F Numbers viewer.\n\n**Orient.** Sheets, dimensions, formula counts.\n\n```bash\nofficecli view \"$FILE\" outline\n```\n\n**Extract.** Plain text dump for content QA or LLM context; scope with `--start` \u002F `--end` \u002F `--cols` for big files.\n\n```bash\nofficecli view \"$FILE\" text --start 1 --end 50 --cols A,B,C\n```\n\nOther `view` modes worth knowing: `annotated` (cell values + types\u002Fformulas + warnings), `stats` (numeric summaries), `issues` (broken formulas, empty sheets, missing refs).\n\n**Inspect one element.** Use XPath-style paths. Always quote — shells glob `[N]`.\n\n```bash\nofficecli get \"$FILE\" \"\u002FSheet1\u002FA1\"            # one cell\nofficecli get \"$FILE\" \"\u002FSheet1\u002FA1:D10\"        # range\nofficecli get \"$FILE\" \"\u002FSheet1\u002Fchart[1]\"      # chart\nofficecli get \"$FILE\" \"\u002FSheet1\u002Ftable[1]\"      # ListObject\nofficecli get \"$FILE\" \"\u002Fnamedrange[1]\"        # workbook-level named range\n```\n\nAdd `--depth N` to expand children; add `--json` for machine output. Full element list: `officecli help xlsx`.\n\n**Query across the workbook.** CSS-like selectors. Use for systematic checks (formula coverage, error cells, empty headers) rather than hand-walking.\n\n```bash\nofficecli query \"$FILE\" 'cell:has(formula)'       # every formula cell\nofficecli query \"$FILE\" 'cell:contains(\"#REF!\")'  # broken references\nofficecli query \"$FILE\" 'cell[type=Number]'       # typed filter\nofficecli query \"$FILE\" 'Sheet1!B[value!=0]'      # sheet-scoped\n```\n\nOperators: `=`, `!=`, `~=` (contains), `>=`, `\u003C=`, `[attr]` (exists).\n\n**Merge cells shortcut.** `officecli query $FILE merge` or `mergedrange` — both are aliases for `mergeCell` (1.0.60+). Returns every merged range in the workbook without hand-walking `\u003CmergeCell>` entries.\n\n**When the data is big enough that a row-walk is useless**, reach for Excel's own analytical elements:\n\n- Build a **pivot table** with `officecli add` (`--type pivottable`) to group\u002Faggregate without writing 20 SUMIFs. Attach a **slicer** (`--type slicer`) to give the reader a filter UI.\n- Drop a **sparkline** (`--type sparkline`) in a row to show per-row trends — cheaper than one line chart per row and they print inline. `type` is a strict enum: **`line | column | stacked`** (plus aliases `winloss` \u002F `win-loss` → `stacked`). Invalid `type=` values hard-fail on 1.0.58+ — no silent fallback to `line` anymore.\n- Run `officecli help xlsx pivottable`, `officecli help xlsx slicer`, `officecli help xlsx sparkline` for the exact prop names.\n\n## Creating & Editing\n\nNinety percent of a build is cells, formulas, formatting, and one or two charts. The verbs: `add` (new element), `set` (change a prop), `remove`, `move`, `swap`, `batch`.\n\n### Cells and formulas\n\nSet a value and its format in one call. Never write `=` at the start of a formula — the CLI strips it.\n\n```bash\nofficecli set \"$FILE\" \u002FSheet1\u002FB5 --prop formula=\"SUM(B2:B4)\" --prop numFmt='$#,##0'\nofficecli set \"$FILE\" \u002FSheet1\u002FC5 --prop formula=\"B5\u002FA5\" --prop numFmt=\"0.0%\"\n```\n\nStructural properties (width, height, freeze, tabColor) live on row \u002F col \u002F sheet nodes:\n\n```bash\nofficecli set \"$FILE\" \"\u002FSheet1\u002Fcol[A]\" --prop width=20\nofficecli set \"$FILE\" \"\u002FSheet1\u002Frow[1]\" --prop height=22\nofficecli set \"$FILE\" \"\u002FSheet1\" --prop freeze=A2 --prop tabColor=1F4E79\n```\n\n### Named ranges\n\nPrefer named ranges over `$B$6` in formulas. They self-document (`GrowthRate` beats `$B$6`) and they let you move the assumption cell without breaking formulas. Because `ref` values contain both `!` and `$`, add them through a batch heredoc:\n\n```bash\ncat \u003C\u003C'EOF' | officecli batch \"$FILE\"\n[\n  {\"command\":\"add\",\"parent\":\"\u002F\",\"type\":\"namedrange\",\"props\":{\"name\":\"GrowthRate\",\"ref\":\"Sheet1!$B$6\"}}\n]\nEOF\n```\n\nSee `officecli help xlsx namedrange` for the full schema.\n\n**Batch JSON does NOT accept shell aliases.** Inside batch `props`, always use the full dotted name — `\"font.color\": \"FF0000\"`, `\"font.size\": 14`, never `\"color\": \"FF0000\"` (ambiguous: text vs fill). On a bare cell, even the shell form is rejected: `--prop color=1F4E79` errors with `ambiguous in cell context — use 'font.color' (text) or 'fill' (bg)`. Rule: in any batch JSON or cell prop, write `font.color` \u002F `fill` explicitly. `parent` should be `\"\u002F\"` for workbook-level elements and `\"\u002FSheetName\"` for sheet-scoped; empty string is not equivalent.\n\n### Charts\n\nChart types live under `officecli help xlsx chart` — the enum is long (20+). Pick the right one for the message: column for category comparison, line for time series, pie only when slices are self-evidently proportional, scatter for correlation. Avoid exotic types unless they answer a specific question.\n\n**Three ways to feed chart data. Pick one per chart — mixing them at add-time is a common trap.**\n\n| Form | Shape | When to use |\n|---|---|---|\n| (a) inline `data` | `--prop data=\"Sales:100,200,300\" --prop categories=\"Jan,Feb,Mar\"` | Tiny demo charts, numbers you will not edit. Source of truth lives in the chart XML, not a cell. |\n| (b) 2D `dataRange` | `--prop dataRange=\"Sheet1!A1:B4\"` (first col = categories, first row = header \u002F series name) | Normal case. Must be **2-D** — single column fails with \"Chart requires data\". |\n| (c) dotted per-series | `--prop series1.name=Sales --prop series1.values=\"Sheet1!B2:B4\" --prop series1.categories=\"Sheet1!A2:A4\"` | Multi-series charts where each series points at non-contiguous ranges, or you want explicit series naming. `series1.values` alone (no `categories`) emits a chart with `1,2,3` as the x-axis. |\n\n**The single-column trap.** `dataRange=\"Sheet1!B2:B13\"` looks like \"value column\" but the engine rejects it with `Chart requires data`. Either widen the range to include the category column (`A2:B13`), or switch to form (c) with explicit `series1.categories`.\n\n**Chart `anchor` and series are immutable after create.** `set chart[N] --prop anchor=...` is rejected (`UNSUPPORTED props: anchor`); likewise new series cannot be appended. To resize, move, or add a series: `officecli remove` the chart, then `officecli add` with the new anchor \u002F full series list. Also note: `remove chart[1]` shifts `chart[2] → chart[1]`, and re-add **appends at the end** — to preserve chart order, remove all and rebuild in order.\n\n**Anchor sizing.** No auto-fit. A column chart with 5-6 categories + 2 series needs roughly `A5:L22` (12 cols × 18 rows) to show all labels uncut. Narrower and X-axis labels clip; wider and the chart can split across pages on print\u002Fexport. If in doubt, start narrow, preview via `view html` (Read the returned HTML path), widen in increments. Page layout (below) is the other half of the fix.\n\n**Chart `dataRange` — always prefix with the sheet.** Even when the chart lives on the same sheet, write `dataRange=\"Summary!A17:C22\"`, not `A17:C22`. The sheet-less form works inconsistently; the prefixed form is 100% reliable.\n\nofficecli adds extended chart types the classic Excel object model lacks: `boxWhisker`, `waterfall`, `funnel`, `histogram`, `treemap`, `sunburst`. Use them when the data calls for them. Known-bad: `chartType=pareto` (produces invalid XML — use `column` or `boxWhisker`).\n\n**NEVER put unreplaced template tokens in chart title \u002F series name \u002F legend \u002F axis title.** `$fy$24`, `{var}`, `\u003CTODO>`, `$VAR`, `{{placeholder}}` render **literally** in the legend — validate passes, but a CFO sees `$fy$24` where \"FY2024\" should be. Always bind to final text or a cell reference (`title=\"FY2024 Revenue\"` or `series1.name=\"Sheet1!A1\"`).\n\n### Conditional formatting\n\nThree common flavors, each with its own prop shape (consult `officecli help xlsx cf`):\n\n- **Color scales**: cells shaded on a gradient by value — `type=colorscale` with `minColor` \u002F `midColor` \u002F `maxColor`.\n- **Data bars**: in-cell bars showing magnitude — `type=databar`. ALWAYS set explicit `min` and `max`; defaults emit invalid XML (see Known Issues).\n- **Formula rules**: highlight row when a condition is true — `type=formulacf` with `formula=\"$C2>1000\"` and a fill\u002Ffont.\n\nRule: apply CF sparingly. A workbook where every cell is colored tells the reader nothing.\n\n### Data validation\n\nInput cells in trackers and templates MUST carry data validation. It's cheap and it stops entire classes of downstream bugs. **Three list-source patterns** — pick based on where the allowed values live.\n\n**(a) Inline list** — allowed values are short and fixed in the rule itself.\n\n```bash\nofficecli add \"$FILE\" \u002FSheet1 --type validation \\\n  --prop sqref=\"C2:C100\" --prop type=list \\\n  --prop formula1=\"Yes,No,Maybe\" \\\n  --prop showError=true --prop errorTitle=\"Invalid\" --prop error=\"Select from list\"\n```\n\n**(b) Named range (preferred for cross-sheet lookups)** — allowed values live in another sheet and may grow. Define the named range first, then reference it. Use a batch heredoc because `ref` contains `!` and `$`:\n\n```bash\ncat \u003C\u003C'EOF' | officecli batch \"$FILE\"\n[\n  {\"command\":\"add\",\"parent\":\"\u002F\",\"type\":\"namedrange\",\"props\":{\"name\":\"StatusList\",\"ref\":\"Lookups!$A$2:$A$4\"}},\n  {\"command\":\"add\",\"parent\":\"\u002FSheet1\",\"type\":\"validation\",\"props\":{\"sqref\":\"B2:B100\",\"type\":\"list\",\"formula1\":\"=StatusList\"}}\n]\nEOF\n```\n\n**(c) Direct cross-sheet range** — no named range, raw `Lookups!$A$2:$A$4` inside `formula1`. Also needs a batch heredoc to keep `!` and `$` intact:\n\n```bash\ncat \u003C\u003C'EOF' | officecli batch \"$FILE\"\n[\n  {\"command\":\"add\",\"parent\":\"\u002FSheet1\",\"type\":\"validation\",\"props\":{\"sqref\":\"C2:C100\",\"type\":\"list\",\"formula1\":\"Lookups!$A$2:$A$4\"}}\n]\nEOF\n```\n\nIf you write the cross-sheet variant as `--prop formula1=...` on the shell, the `!` gets shell-mangled into `\\!` and the dropdown will silently fall back to no list. Verify with `officecli get \"$FILE\" \u002FSheet1\u002Fvalidation[N]` — `formula1=` must show a plain `!`, no backslash.\n\nOther common `type` values: `decimal`, `whole`, `date`, `textLength`, `custom`. See `officecli help xlsx validation` for operators and the full prop list.\n\n### Other elements (one-liners)\n\n- **Tables** (ListObjects) — `add --type table` with a range; gives auto-filter + structured refs. `officecli help xlsx table`.\n- **Comments** — `add --type comment`; use for documenting hardcoded assumptions. `officecli help xlsx comment`.\n- **Sheet reordering** — `officecli move`, not `swap`. `swap` only works on row\u002Fcell paths.\n\n## Chart Axis-by-Role\n\nEditing a chart axis in place is cheaper than rebuilding the chart. Address axes by **role** (`value` = Y, `category` = X), not by index — the XML order isn't stable.\n\n```bash\nofficecli get \"$FILE\" \"\u002FSheet1\u002Fchart[1]\u002Faxis[@role=value]\"\nofficecli set \"$FILE\" \"\u002FSheet1\u002Fchart[1]\u002Faxis[@role=value]\" --prop min=0 --prop max=100000\nofficecli set \"$FILE\" \"\u002FSheet1\u002Fchart[1]\u002Faxis[@role=category]\" --prop title=\"Month\"\n```\n\nSafe props: `title`, `min`, `max`, `majorGridlines`, `visible`. Do NOT use `labelRotation` — it emits invalid XML today (see Known Issues).\n\n## QA (Required)\n\n**Assume there are problems. Your job is to find them.**\n\nYour first workbook is almost never correct. Treat QA as a bug hunt, not a confirmation step. If you found zero issues on first inspection, you were not looking hard enough. The formulas look fine **until** you check two of them against source cells.\n\n### Minimum cycle before \"done\"\n\n1. `officecli view \"$FILE\" issues` — empty sheets, broken formulas, missing refs.\n2. `officecli view \"$FILE\" annotated` (sample ranges) — values + types + warnings.\n3. For every Excel error type, query it:\n   ```bash\n   officecli query \"$FILE\" 'cell:contains(\"#REF!\")'\n   officecli query \"$FILE\" 'cell:contains(\"#DIV\u002F0!\")'\n   officecli query \"$FILE\" 'cell:contains(\"#VALUE!\")'\n   officecli query \"$FILE\" 'cell:contains(\"#NAME?\")'\n   officecli query \"$FILE\" 'cell:contains(\"#N\u002FA\")'\n   ```\n4. `officecli validate \"$FILE\"` — close any resident first (see Known Issues).\n5. **Visual pass — walk every sheet via the HTML preview.** Run `officecli view \"$FILE\" html` and Read the returned HTML path. Each sheet renders with charts inline. Scan for `###`, truncated titles, placeholder tokens (`$fy$24`, `{var}`, `\u003CTODO>`), sliced charts, white-slice pie charts, empty chart anchors — **STOP and fix before declaring done**. \"validate pass\" is not delivery; \"the preview looks like a real workbook\" is delivery. For human preview, run `officecli watch \"$FILE\"` (user opens the live preview at their own discretion) or have them open the `.xlsx` directly in Excel \u002F WPS \u002F Numbers.\n6. **Print layout fix (wide tables \u002F multi-chart sheets).** When a sheet holds a chart or a wide table and the user will print it, set per-sheet page layout so it fits on one page:\n   ```bash\n   officecli set \"$FILE\" \"\u002FSummary\" --prop orientation=landscape --prop fitToPage=true\n   ```\n   Outcome: each sheet's print layout is one page with no mid-chart splits. Apply to every sheet that holds a chart or a > 8-column table.\n7. If anything failed, fix, then **rerun the full cycle**. One fix commonly creates another problem.\n\n`officecli view issues` + `view html` are the structural QA pair: `issues` catches broken formulas and empty sheets; `view html` (Read the returned HTML path) catches `###`, truncation, and token leakage. Chart fill colors \u002F theme tints can vary across viewers — spot-check in the user's target viewer when color fidelity matters.\n\n### Formula verification checklist\n\n- [ ] Pick 2-3 formulas at random. Run `officecli get` on each. Confirm the formula string is what you intended **and** `cachedValue=` is what you expect — arithmetic in your head.\n- [ ] **Cached value sanity on every summary cell.** Any cell that aggregates (COUNTA \u002F COUNTIF \u002F SUMPRODUCT \u002F INDEX&MATCH) must have a plausible `cachedValue`. If a progress tracker shows `199 \u002F 199 \u002F 100%` on a blank template, the cache is lying — re-touch the formula via `set` (forces recompute) or manually set a correct cached value. Do NOT ship \"validate passes but the numbers are fiction\".\n- [ ] **Spot-check one cell per numeric column.** `%` columns showing integer `0.0%` throughout means the denominator is wrong or the numerator is cached stale — investigate one cell, fix the pattern.\n- [ ] Ranges include every row: off-by-one on `SUM(B2:B12)` when data goes to `B13` is the most common bug.\n- [ ] Cross-sheet formulas (`Sheet1!A1`) contain no `\\!`. If `officecli get` shows `Sheet1\\!A1`, the `!` was shell-corrupted — delete and re-enter via batch\u002Fheredoc.\n- [ ] Named ranges (`officecli get \"$FILE\" \"\u002Fnamedrange[1]\"`) point at what their names claim.\n- [ ] Every `\u002F` denominator is guarded — `IFERROR(x\u002Fy, 0)` or `IF(y=0, 0, x\u002Fy)`.\n- [ ] Chart data vs source cells: for every chart with inline data, spot-check data points against `officecli get` of the source cells.\n- [ ] Chart title \u002F series name \u002F legend contain **no** unreplaced tokens (`$...$`, `{var}`, `\u003CTODO>`). Grep the chart via `officecli get \u002FSheet1\u002Fchart[N]`.\n\n### Template QA\n\nWhen editing a template, check for leftover placeholders — they look like content and slip past `validate`:\n\n```bash\nofficecli query \"$FILE\" 'cell:contains(\"{{\")'\nofficecli query \"$FILE\" 'cell:contains(\"xxxx\")'\nofficecli query \"$FILE\" 'cell:contains(\"TBD\")'\n```\n\n### Fresh eyes\n\nWhen you finish a workbook, open it fresh. Read `view text` \u002F HTML preview top-to-bottom as if you are a new reviewer — look for formulas, numbers that look off, formatting inconsistency, missing data.\n\n### Honest limit\n\n`validate` catches schema errors, not design errors. A workbook can pass `validate` with every number wrong. The checklist above — especially spot-checking formulas against source cells — is how you catch what validation can't.\n\n## Known Issues & Pitfalls\n\n### The cross-sheet `!` trap (short)\n\nShells (bash history expansion, zsh splitting) and CLI arg parsing mangle `!` in `Sheet1!A1` into `\\!`. A formula containing `\\!` is silently broken — it renders as literal text and references nothing.\n\n**Fix.** Use a batch heredoc with single-quoted delimiter (`\u003C\u003C'EOF'`), which disables all shell expansion:\n\n```bash\ncat \u003C\u003C'EOF' | officecli batch \"$FILE\"\n[{\"command\":\"set\",\"path\":\"\u002FSummary\u002FB2\",\"props\":{\"formula\":\"Revenue!B13\"}}]\nEOF\n```\n\n**Verify.** After writing, `officecli get` the cell; `formula=` must show a plain `!` with no backslash.\n\n### CLI bug backlog (short)\n\nAvoid these until fixed; they produce invalid XML or silent breakage.\n\n- **`chartType=pareto`** — emits empty `cx:axisId val=\"\"`; `validate` fails after `close`. Substitute `column` or `boxWhisker`.\n- **`labelRotation` on axis-by-role** — inserts bad `a:endParaRPr`. Use `title`\u002F`min`\u002F`max`\u002F`majorGridlines`\u002F`visible` only.\n- **Data bar without explicit min\u002Fmax** — default cfvo `val=\"\"` is invalid. Always pass `--prop min=N --prop max=N`.\n- **Chart `anchor` and series are immutable after create** — to resize\u002Fmove\u002Fadd-series: `remove` + `add`. `remove chart[N]` shifts subsequent indices down; re-add appends at end.\n- **`validate` while resident open** — reports spurious `tableParts` \u002F `drawing` errors. Always `close` first.\n- **Batch + resident for formulas — avoid.** Observed deadlocks (CPU 99%, `main pipe busy`, kill -9 required) for cross-sheet formula batches even at 3-5 ops; the prior \"≤ 12 ops safe\" guideline is **not reliable**. Rule: **cross-sheet formulas go through non-resident one-big-batch OR individual `set`** (100% reliable). Pure value-set batches (no formulas) stay reliable at 50-80+ ops even in resident. **Multiple officecli resident processes on the same machine also contend** — if another agent\u002Fsession is running resident, expect non-deterministic hangs.\n- **Conditional formatting naming asymmetry** — the element name for `--type` is `conditionalformatting`; the path suffix is `\u002Fcf[N]`. Use `officecli help xlsx conditionalformatting` for schema, `\u002Fcf[N]` for paths.\n- **Sheet `position` prop on add** — help says Add processes `position`, but the prop is often ignored. Reorder with `officecli move --index` \u002F `--after` \u002F `--before` after creating the sheet.\n- **`remove \u002Fsheet[N]` cascade guard** — 1.0.59+ rejects sheet remove\u002Frename when the sheet is referenced by validation \u002F conditional format \u002F sparkline \u002F hyperlink \u002F named range on another sheet. Remove those dependent elements first, then remove the sheet.\n- **Batch JSON rejects cell `color` alias** — inside batch `props`, `\"color\": \"FF0000\"` errors `ambiguous in cell context — use 'font.color' (text) or 'fill' (bg)`. The CLI at shell level accepts `--prop color=...` \u002F `--prop size=14` as aliases on non-cell elements, but inside batch JSON on a cell always write the full dotted name: `\"font.color\"`, `\"font.size\"`, `\"font.name\"`.\n- **`SUMPRODUCT((range=criterion)*values)` caches `0` on 1.0.63** — the CLI calc engine does not evaluate array-predicate `SUMPRODUCT` at write-time; runtime Excel\u002FWPS compute fine but the cached `0` ships to non-recalculating readers. **Helper-column fallback:** add a column `F` on the source sheet with `=C2*D2` per row, then aggregate via `=SUMIF(B:B, \"Region X\", F:F)`. Caches correctly, audits cleanly, and survives non-recalculating viewers.\n\n### Renderer caveats (cross-viewer color fidelity)\n\n`officecli view html` is the right tool for structural QA (overflow, truncation, placeholder leakage, layout) — Read the returned HTML path. Some chart rendering details vary across the viewer the end user opens the file in. Observed divergences:\n\n- **Pie \u002F doughnut fill colors may collapse to a single theme tint** in some viewers (slices look \"all white\" or \"all one color\"). The file may be fine in the user's target viewer.\n- **Line chart \u002F column chart series colors may drift** from the workbook theme in some viewers.\n- **Form-control checkboxes may render as double-boxed** in some viewers.\n\nBefore calling a color or chart \"broken\", open the file in the user's actual target viewer. If it looks correct there, the problem is viewer rendering, not data — do not chase it. The CLI's structural checks (`###`, truncation, placeholder text, layout) remain authoritative.\n\n### Escape layers (shell quoting is above; these are the extras)\n\nThe CLI does not interpret `\\$` \u002F `\\t` \u002F `\\n` — they land as literal characters. Shell-level rules are in L25-30. Two additional layers:\n\n- **JSON level (batch).** Standard JSON escapes — `\"\\n\"`, `\"\\t\"`, `\"\\\"\"`. A real backslash in the final string is `\"\\\\\\\\\"`.\n- **Excel level.** `\\n` in a cell for line break → write `\"\\n\"` **inside JSON**. In a shell-quoted prop it stays literal (Excel shows `\\n` text). When in doubt, `officecli get` the cell and compare character-for-character.\n\n### Other common pitfalls\n\n| Pitfall | Fix |\n|---|---|\n| `--name \"foo\"` | All attrs go through `--prop`: `--prop name=\"foo\"` |\n| Guessing a prop name | `officecli help xlsx \u003Celement>` — don't improvise |\n| `--prop color=...` on a cell | Ambiguous — use `font.color` (text) or `fill` (bg). Also applies inside batch JSON: always use full dotted names, never shell aliases |\n| `#FF0000` hex colors | Drop the `#`: `FF0000` |\n| `--index` vs `[N]` | `--index` is 0-based (array); `[N]` paths are 1-based (XPath) |\n| Unquoted `[N]` in zsh\u002Fbash | Quote every path: `\"\u002FSheet1\u002Frow[1]\"` |\n| Sheet name with spaces | Quote full path: `\"\u002FMy Sheet\u002FA1\"` |\n| Year showing as `2,026` | `--prop type=string` or `numFmt=\"@\"` |\n| Modifying a file open in Excel | Close it in Excel first |\n| `swap` not reordering sheets | `swap` is for rows\u002Fcells. Use `move --after` \u002F `--before` \u002F `--index` for sheets |\n| Cached values missing after write | New formulas get cached values when a human opens the file; `validate` accepts them either way |\n",{"name":5,"description":7},"main","1f321f8966b6741235f35f79c97c0ffdcffb11ba","crates\u002Fbackend\u002Fnomifun-app\u002Fassets\u002Fbuiltin-skills\u002Fofficecli-xlsx","https:\u002F\u002Fgithub.com\u002Fmakeyzhang-cpu\u002Fgeekclaw","https:\u002F\u002Fgithub.com\u002Fmakeyzhang-cpu","2026-11-08 16:23:21",{"source":8,"skillName":5,"commands":30,"prompt":40,"zipAvailable":41},[31,34,37],{"tool":32,"command":33},"npx","npx skills add makeyzhang-cpu\u002Fgeekclaw --skill officecli-xlsx",{"tool":35,"command":36},"bunx","bunx skills add makeyzhang-cpu\u002Fgeekclaw --skill officecli-xlsx",{"tool":38,"command":39},"pnpm","pnpm dlx skills add makeyzhang-cpu\u002Fgeekclaw --skill officecli-xlsx","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmakeyzhang-cpu\u002Fgeekclaw\u002Fblob\u002Fmain\u002Fcrates\u002Fbackend\u002Fnomifun-app\u002Fassets\u002Fbuiltin-skills\u002Fofficecli-xlsx\u002FSKILL.md",true,[],[44,51,58,65,72,79],{"skillNo":45,"name":46,"nameZh":6,"description":47,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":48,"categories":49,"keywords":50,"publishedAt":18},"01M7BYJ19XV75TDGRGXBFJN1T4","drive-geekclaw","Use to connect to and drive a GeekClaw instance from an external agent (Claude Code \u002F Cursor \u002F any MCP client). Drive its browser \u002F computer \u002F knowledge base \u002F files and manage the platform over MCP or REST, with a per-companion access token (you run AS the bound companion). Use this whenever the user asks to control, automate, or hand work off to \"GeekClaw\", \"their GeekClaw\", \"the desktop companion\", or a running GeekClaw server.","https:\u002F\u002Fgithub.com\u002Fmakeyzhang-cpu\u002Fgeekclaw\u002Fblob\u002Fmain\u002Fdocs\u002Fskills\u002Fdrive-nomifun\u002FSKILL.md",[],[],{"skillNo":52,"name":53,"nameZh":6,"description":54,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":55,"categories":56,"keywords":57,"publishedAt":18},"01M7BYHZBZNHHBX8M87JZ6Y031","example-skill","Fixture skill used by startup_materialize integration tests.","https:\u002F\u002Fgithub.com\u002Fmakeyzhang-cpu\u002Fgeekclaw\u002Fblob\u002Fmain\u002Fcrates\u002Fbackend\u002Fnomifun-extension\u002Ftests\u002Ffixtures\u002Fbuiltin-skills-fixture\u002Fexample-skill\u002FSKILL.md",[],[],{"skillNo":59,"name":60,"nameZh":6,"description":61,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":18},"01M7BYHWFXC17GE9SXDK1X3GTD","ui-ux-pro-max","Professional UI\u002FUX design research skill with a bundled searchable database for product patterns, visual styles, color palettes, typography, landing-page structure, dashboard charts, UX practices, and stack guidance. Use when designing, building, reviewing, or improving interfaces.","https:\u002F\u002Fgithub.com\u002Fmakeyzhang-cpu\u002Fgeekclaw\u002Fblob\u002Fmain\u002Fcrates\u002Fbackend\u002Fnomifun-app\u002Fassets\u002Fbuiltin-skills\u002Fui-ux-pro-max\u002FSKILL.md",[],[],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":18},"01M7BYHR24XK92Z2YYQHK2732Y","planning-with-files","Maintain durable task plans, findings, and progress logs in workspace files for long-running or research-heavy work. Use when a task spans many steps or sessions, needs an auditable evidence trail, or risks losing important decisions to context limits. Do not use for short tasks that fit comfortably in the active conversation.","https:\u002F\u002Fgithub.com\u002Fmakeyzhang-cpu\u002Fgeekclaw\u002Fblob\u002Fmain\u002Fcrates\u002Fbackend\u002Fnomifun-app\u002Fassets\u002Fbuiltin-skills\u002Fplanning-with-files\u002FSKILL.md",[],[],{"skillNo":73,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":18},"01M7BYHKQ6A4CNTQB0JXRJ5AXX","officecli","Create, analyze, proofread, and modify Office documents (.docx, .xlsx, .pptx) using the officecli CLI tool. Use when the user wants to create, inspect, check formatting, find issues, add charts, or modify Office documents.","https:\u002F\u002Fgithub.com\u002Fmakeyzhang-cpu\u002Fgeekclaw\u002Fblob\u002Fmain\u002Fcrates\u002Fbackend\u002Fnomifun-app\u002Fassets\u002Fbuiltin-skills\u002Fofficecli\u002FSKILL.md",[],[],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":18},"01M7BYH28A6TEAT4ATWEJZ9M3F","officecli-word-form","Use this skill to create fillable Word forms (.docx) with real Content Controls (SDT) + legacy FormField checkboxes + MERGEFIELD mail-merge placeholders + document protection. Trigger on: 'fillable form', 'form fields', 'content controls', 'SDT', 'word form', 'fill in', 'only editable fields', 'protect document', 'onboarding form', 'HR intake', 'survey template', 'contract \u002F SOW template', 'mail-merge template', 'compliance checklist', 'medical intake questionnaire'. Output is a single .docx where specific fields are editable and the rest is locked. This skill is INDEPENDENT, not a scene layer on docx — payload is `\u003Cw:sdt>` + `\u003Cw:ffData>` + `\u003Cw:fldChar>` + `documentProtection`, none of which docx base skill covers. Do NOT trigger for regular reports, letters, memos, academic papers, pitch decks, or any document with no user-fillable fields — route those to officecli-docx or its scene layers.","https:\u002F\u002Fgithub.com\u002Fmakeyzhang-cpu\u002Fgeekclaw\u002Fblob\u002Fmain\u002Fcrates\u002Fbackend\u002Fnomifun-app\u002Fassets\u002Fbuiltin-skills\u002Fofficecli-word-form\u002FSKILL.md",[],[]]