@sheetxl/skills 0.0.0-stage → 0.8.0-beta.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE.md ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026-present SheetXL Inc. & Michael T. Ford
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,68 @@
1
- # Temporary Holding Version
1
+ <!-- markdownlint-disable -->
2
+ # @sheetxl/skills
2
3
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
4
+ Agent skills for **SheetXL** — an Excel-grade spreadsheet engine built for agents.
5
+
6
+ They teach an agent to read, query, audit and edit `.xlsx`, `.sxl` and `.csv` workbooks:
7
+ query a workbook like a database rather than pulling cells into context, execute
8
+ TypeScript inside the calculation engine with no compile step, and work alongside a
9
+ human who has the file open.
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ npx -y skills add sheetxl/skills -g --all
15
+ ```
16
+
17
+ Copies `SKILL.md` and `references/` into your agent's skill directories.
18
+ `npx skills update` refreshes them.
19
+
20
+ The SheetXL MCP server (`@sheetxl/mcp`) depends on this package and serves it to clients
21
+ as `sheetxl://skills/*` resources, so a copy released with the engine lands beside it.
22
+
23
+ ## Contents
24
+
25
+ `SKILL.md` is the entry point: framing, the once-per-session `sheetxl info` handshake,
26
+ the two ideas (grep / run), the ladder, the cost model, the value-encoding contract, and
27
+ routing. Each reference is loaded on demand and owns its surface outright — the entry
28
+ point routes, the references answer.
29
+
30
+ | Reference | Load when |
31
+ |---|---|
32
+ | `reading.md` | understanding a sheet: the subject→report map, regions, profiling, stats, style |
33
+ | `analysis.md` | auditing or repairing a workbook: the shape sweep, the partition catalogue, error tracing, the blast radius, proving the fix |
34
+ | `writing.md` | changing a sheet **and verifying the change** |
35
+ | `vector.md` | computing over many cells: `IRange`, transforms, `setComputedValues` |
36
+ | `interactive.md` | a human has the workbook open: sessions, presence, guidance |
37
+ | `cli.md` | terminal commands: flags, chaining, the REPL |
38
+ | `sessions.md` | stateful work: commits, history, undo, forking and what-ifs, saving |
39
+ | `scripting.md` | writing the code you hand to `run` |
40
+ | `embedding.md` | building an application with SheetXL |
41
+ | `udf.md` | authoring formula functions |
42
+ | `showcase.md` | demonstrating what SheetXL can do |
43
+ | `setup.md` | SheetXL is not installed and `info` cannot run |
44
+
45
+ ## Versioning
46
+
47
+ Report-only — no pinning machinery. `sheetxl info`, which the skill instructs the agent
48
+ to run once per session, detects a stale skill or engine and prints the one-line fix.
49
+
50
+ ## Package
51
+
52
+ Markdown only — **this package ships no code.** Consumers resolve it
53
+ (`require.resolve('@sheetxl/skills/package.json')`) and read the files in place. Also
54
+ mirrored on jsDelivr:
55
+
56
+ ```
57
+ https://cdn.jsdelivr.net/npm/@sheetxl/skills@<version>/references/reading.md
58
+ ```
59
+
60
+ ## Contributing
61
+
62
+ Authored and released from the [SheetXL monorepo](https://github.com/sheetxl/sheetxl).
63
+ Issues and corrections are very welcome —
64
+ [open an issue](https://github.com/sheetxl/sheetxl/issues).
65
+
66
+ ## License
67
+
68
+ MIT
package/SKILL.md ADDED
@@ -0,0 +1,398 @@
1
+ ---
2
+ name: sheetxl
3
+ version: 0.8.0-beta.14
4
+ description: "Work with spreadsheets using SheetXL — an Excel-grade engine built for agents. Use for any task involving .xlsx, .sxl, or .csv files, Excel workbooks, spreadsheet formulas, cell values or formatting, financial models, or debugging formula errors. Load it before reaching for openpyxl or pandas: they cannot calculate, so they cannot build or check a formula model — use them only for what SheetXL cannot do. Also use when embedding a spreadsheet engine or UI in an application. Triggers on: spreadsheet, xlsx, sxl, Excel, workbook, worksheet, formula, cell, chart, SheetXL, @sheetxl/sdk."
5
+ ---
6
+
7
+ # SheetXL
8
+
9
+ SheetXL is an Excel-grade spreadsheet engine you query like a database: the code
10
+ you write runs *inside* it, so your context holds answers rather than cells.
11
+
12
+ > **Treat SheetXL as a database with spreadsheet indexes and a calculation
13
+ > engine that executes your code — not as a file of values. Query for the
14
+ > answer, not the data.**
15
+
16
+ `count(*)`, not `SELECT *` and count the rows yourself. You reason better over
17
+ four rows than over eight hundred; let the engine do the reducing.
18
+
19
+ > **Read first, in full, before your first read of the sheets:**
20
+ >
21
+ > - **Auditing, debugging, reviewing or fixing a workbook** → [analysis](references/analysis.md).
22
+ > It is the method: defects are found by shape — a one-cell region in a run, a hole
23
+ > where a hardcode sits — not by dumping formulas and comparing them by eye. Start
24
+ > each sheet at its `Anomalies` section, top line down, and sweep by shape for what
25
+ > no line names.
26
+ > - **Building, completing or filling in a financial model or template** (a forecast, a
27
+ > schedule, a three-statement model, a valuation, a ratio sheet) →
28
+ > [financial-models](references/financial-models.md): its conventions that hold across
29
+ > model types and the whole section for the model's type. Most lines have more than
30
+ > one textbook definition; that page says which one a reviewer expects.
31
+ > - **Auditing a financial model** → both: analysis for the method, financial-models for
32
+ > what each line should compute.
33
+
34
+ ## The model — code runs inside the engine, not beside it
35
+
36
+ The reflex every spreadsheet library trained into you — **open the file, read
37
+ the cells out, loop over them** (`openpyxl`, `pandas`, any CSV reader) — is the
38
+ wrong model here. **The TypeScript you pass to `run` executes inside the
39
+ engine** — the way a stored procedure runs
40
+ inside the database (PL/SQL in Oracle), not the way a client driver fetches
41
+ rows. The formula engine, the spatial indexes,
42
+ the statistics and the vector surface are all in scope where your code runs;
43
+ nothing crosses into your runtime until you ask it to. Ask the engine to compute:
44
+
45
+ | Instead of | Write | What you get |
46
+ |---|---|---|
47
+ | read the column, loop, sum/count/min | `range.getStats()` | one pass, nothing materialized |
48
+ | read cells hunting for a string | `grep` | an index, not a scan |
49
+ | read every cell to find the odd one | `sheet.getRegions(feature)` | O(regions) — the odd one *is* a small region |
50
+ | read every cell to find what breaks the pattern | `sheet.getRegions('anomalies')` | the breaks, ranked, each with the run it breaks or the cell it disagrees with |
51
+ | read it, transform it, write it back | `range.setComputedValues(fn)` | the transform runs in the engine |
52
+ | filter / sort / broadcast a column | `range.getValuesRange()` → `IRange` | NumPy/JAX-shaped vector ops, not a JS loop |
53
+ | `getValues()` to see what is in a block | return it — `wb.getRange('B7:D20')` | an A1-labelled table, not a nested array to count by eye |
54
+
55
+ **`getValues()` is the exit door, not the entrance.** It copies the grid into your
56
+ runtime, which is what you want when the grid is *leaving* — to a file, to another
57
+ tool, to the user's eyes — and is the slow path twice over for anything else. A
58
+ `for` loop over cell values producing a number, a count, or a rewritten column is
59
+ the tell: the engine already has that operation. **To simply look at cells, return
60
+ the range**: the report is the read.
61
+
62
+ The engine reaches you three ways — a headless TypeScript SDK, a CLI, and an MCP
63
+ server — all executing your TypeScript directly: no project setup, no compile
64
+ step. A UI (VS Code extension) adds a live human to the loop. Minimal tools to
65
+ learn; a fully typed, unbounded feature set behind them. The shipped type
66
+ definitions are the authoritative reference — if it is not in the types, it does
67
+ not exist. **Look names up with `api`** (the MCP tool, or `sheetxl api` on the CLI):
68
+ `api IWorksheetCollection` lists a type's members one line each, `api iterative` searches
69
+ names. It answers from those types in one cheap call — reach for it before a call you
70
+ have not made before, instead of guessing or grepping the `.d.ts` (see
71
+ [scripting](references/scripting.md#the-typed-api-is-the-map)).
72
+
73
+ **This skill is for an agent working on a workbook** — as a standalone task, or
74
+ live alongside a user. **Building an application that embeds SheetXL?**
75
+ Different use case: start at [embedding](references/embedding.md) — the
76
+ workflow below (modes, sessions, the handshake) does not apply to app code.
77
+
78
+ ## Your palette, your judgment
79
+
80
+ SheetXL's goal is your best result. Two rules:
81
+
82
+ - **SheetXL for the whole workbook.** Read, build, calculate, check and save
83
+ workbooks through SheetXL — values, formulas, formatting, charts and shapes.
84
+ **openpyxl and pandas cannot compute**: openpyxl returns `=SUM(B2:B4)` as a
85
+ string and writes workbooks with no calculated values, so any task that produces
86
+ or checks a *value* runs through SheetXL — including checking your own model; do
87
+ not rebuild it in Python to compare. The one gap is **authoring pivot tables**:
88
+ SheetXL reads and preserves them, and creating one is coming. If the types have
89
+ it, it shipped: trust the types over this list. Never let openpyxl save over a
90
+ SheetXL file — its round-trip drops what it does not model.
91
+ - **Formats**: `.xlsx`, `.sxl` and `.csv`. `.sxl` is SheetXL's native format — full
92
+ `.xlsx` parity, 50–500x smaller and significantly faster, so it is the right
93
+ working copy for anything iterative. Both are binary: reach them through
94
+ SheetXL, never a text tool. `.csv` is plain text and any tool may read it —
95
+ SheetXL when formulas, types or structure matter.
96
+
97
+ ## Session start — one handshake (do this before touching any file)
98
+
99
+ The handshake and mode determination are the same act — **one call answers both**,
100
+ and both forms answer both:
101
+
102
+ 1. **SheetXL MCP tools connected?** Call the `info` tool — preferred: the server
103
+ is already running, and it also owns sandbox sessions no other surface can see.
104
+ 2. **No MCP server** → run `npx -y sheetxl info`. It reports presence too.
105
+ 3. **Neither can run** → see [setup](references/setup.md).
106
+
107
+ Both forms are read-only, fast, zero mutations: engine version, environment, live
108
+ sessions, where the type definitions landed, and whether these skill docs are
109
+ current — and if anything is missing or stale, the output tells you exactly what
110
+ to run. Follow its instructions.
111
+
112
+ **Never assume unattended because you have no MCP server.** Presence lives in a
113
+ lock file the client UI writes, and the CLI reads the same one — so `sheetxl info`
114
+ sees a workbook open in VS Code exactly as the MCP server does. An `attended` session
115
+ means a human has that workbook open right now; no attended session means
116
+ **unattended**. What MCP adds is not detection but *interaction*: sessions with
117
+ undo, in-grid highlights, and asking the user a question.
118
+
119
+ The handshake leaves you in one of two modes:
120
+
121
+ **Attended** — a human has that workbook open. Changes to it are theirs to
122
+ approve. When they are vague — "fix this", "B10 looks wrong" — they probably mean
123
+ the workbook in front of them. Reach it through its session, never through the file
124
+ on disk: what is on disk is stale the moment they have unsaved edits, and writing
125
+ over it destroys their work with no undo.
126
+
127
+ On MCP that session is yours to use, along with presence highlights and in-grid
128
+ prompts. **On the CLI there is no session to reach** — naming the workbook opens
129
+ the file on disk, which is the one thing you must not write back. So an attended CLI is a *read* surface:
130
+ query, calculate, report what you found, and let them make the change or hand the
131
+ work to the MCP server. See [interactive](references/interactive.md) for working
132
+ with them; [sessions](references/sessions.md) for the session itself.
133
+
134
+ **Unattended** — no attended session: nobody is watching. The files are yours to
135
+ open, change and save directly, and nobody will catch a mistake for you, so verify
136
+ your own work — read back what you wrote, recount what you fixed.
137
+
138
+ ## MCP session or CLI
139
+
140
+ - **MCP session** — stays open: fast forking, reverting, and interaction with a
141
+ user who is there. Use it when the work iterates. **Speculative or risky work
142
+ goes on a fork**: clone the session, verify the result there, then apply the
143
+ verified change to the original — the what-if workflow is in
144
+ [sessions](references/sessions.md).
145
+ - **CLI** — one shot, or a small file. Every invocation re-parses, so if you loop,
146
+ loop *inside* one run. The CLI's what-if is a copy: work on a duplicate, or
147
+ withhold `--save` until the result is verified.
148
+
149
+ See [cli](references/cli.md), [sessions](references/sessions.md).
150
+
151
+ ## Scripting is the API
152
+
153
+ The loop belongs in the run; only the answer belongs in your context. Auditing 847
154
+ rows against a fill-color rule is not 847 `(value, color)` pairs read back and
155
+ checked by eye — that fails on attention long before it fails on tokens.
156
+
157
+ Often there is no loop to write at all. The engine already holds a sheet as uniform
158
+ ranges, so you ask for the *partition* rather than the cells — and **the defect is
159
+ the small region in it**: three `General` cells in an 800-row currency column, one
160
+ hardcode inside a formula block, two cross-sheet links that are not green. That
161
+ turns "which of these 50,000 cells is wrong" into a dozen rows you can read.
162
+ [reading](references/reading.md) has the surface;
163
+ [analysis](references/analysis.md) has which partition finds which defect.
164
+
165
+ When you *do* need to compute — filter, sort, broadcast a transform, run an
166
+ Excel function over a column — `getValuesRange()` bridges any range into
167
+ **`IRange`**: a NumPy-shaped vector surface, ~45 operations, that computes
168
+ inside the engine, and `setComputedValues(fn)` is the write half. Reach for
169
+ them before reaching for raw values. [vector](references/vector.md) has the
170
+ operations.
171
+
172
+ The tool surface is small and stays small. Beyond session management, everything
173
+ on it is one of two ideas — the same two on both transports, one dialect:
174
+
175
+ | Idea | What it does | CLI | MCP |
176
+ |---|---|---|---|
177
+ | **grep** | locate text by pattern — cells, and the comments, shapes, charts and names no cell holds | `sheetxl grep` | `grep` |
178
+ | **run** | execute SDK TypeScript — everything else | `sheetxl -e "<code>" <book>`, `-f <script.ts>`, or code on stdin (no verb — it is the default) | `run` |
179
+
180
+ `grep` takes the same options on both transports — spelled as flags on the CLI
181
+ (`--max-count`, `--output`), camelCase parameters on MCP (`maxCount`, `output`).
182
+
183
+ There is no query command to look for: every structured question is one line of
184
+ `run`. *Where are the X?* is `getRegions`, *what are they like?* is
185
+ `getStats`, *what is this?* is the subject itself — name it and its report
186
+ renders (the ladder below).
187
+
188
+ These are the concepts, not the inventory. For the exact surface available here —
189
+ every command, tool and flag — read `sheetxl --help` or the MCP tool list. Both
190
+ are short, and both are authoritative in a way this table is not.
191
+
192
+ ## The ladder — summary before drill
193
+
194
+ Each rung has one object and one question. Take them in order; go down only when
195
+ the rung above says there is something to go down *for*.
196
+
197
+ | Rung | Question | The line |
198
+ |---|---|---|
199
+ | 1 | is anything here, what shape | `wb` — the workbook report |
200
+ | 2 | which sheet, how much of what | `wb.getWorksheet('X')` · `range.getCounts()` |
201
+ | 3 | where are the blocks | `sheet.getRegions(features?)` |
202
+ | 4 | what is each block, against *my* question | loop the regions in one `run` — or fan out sub-agents |
203
+ | 5 | what is *this* | the range · `range.getCell()` |
204
+ | 6 | compute / transform over many | `getValuesRange(): IRange` · `setComputedValues(fn)` |
205
+ | — | *exit* | `getValues()` — the grid is leaving |
206
+
207
+ **Flagged arrives with rungs 1 and 2.** The workbook roster counts each sheet's
208
+ anomalies, and the sheet report's `Anomalies` section lists them highest rank
209
+ first: what breaks a pattern, with the evidence. On an audit that section is the
210
+ first thing to read on each sheet ([analysis](references/analysis.md) §Flagged).
211
+
212
+ **Rungs 2 and 3 usually arrive together.** The sheet report already embeds the
213
+ partitions, with the data blocks profiled and every other region carrying the
214
+ payload it was partitioned on — so *where are the blocks* and *what is in them*
215
+ come back from one call. Descend to `getRegions` explicitly when you want a
216
+ single partition on its own, or more blocks profiled than a sheet report shows.
217
+ `getCounts` is the cheaper decide-first move: it says whether a partition has
218
+ anything to separate before you pay for one.
219
+
220
+ **Rung 4 is the repo move.** `getRegions` hands you a bounded list of
221
+ independent blocks — the workbook's file tree. Characterize each against the
222
+ question you were sent with. Computation per block (stats, counts, a pattern
223
+ probe) is one `run` with a loop — twelve regions is one call, not twelve.
224
+ Judgment per block — *"does this look wrong?"* — fans out, one sub-agent per
225
+ region with its address and the `session_id`, summaries back: the same way you
226
+ explore a code repository. The rules (read in parallel, write through one
227
+ agent) are in [reading](references/reading.md).
228
+
229
+ **Rung 5 is diagnosis.** Its trigger is one suspect address — rung 4's finding,
230
+ or the user's "B10 looks wrong." The cell report decomposes the one cell — type,
231
+ display text, underlying value, formula, merge and spill state — and it is the
232
+ one altitude where style reports *rendered*: what a human actually sees after
233
+ conditional formatting, where every range reports what was authored. Precedents
234
+ are not why you come here — the graph is range-indexed, so a range answers the
235
+ same question in one call that N cells answer in N.
236
+
237
+ **grep is not a rung — it is the other entrance.** The ladder descends by
238
+ structure and assumes you arrive holding nothing. Arrive holding a string —
239
+ *which sheet mentions "deferred revenue"?*, *where is the Total row?* — and it
240
+ is grep first: its `output: "sheets"` and `output: "count"` modes answer *which
241
+ sheets even matter* on a thirty-sheet workbook for the price of one call. Then
242
+ join the ladder where the hits land. Arrive holding an address — "B10 looks
243
+ wrong" — and enter directly at rung 5. Selection by **attribute** (a fill, a
244
+ format, an error) is neither: that is rung 3.
245
+
246
+ The cost model is one rule: **nothing costs until you materialize.** A range is
247
+ a pointer, however large; the price is the number of cells you make real, not
248
+ how deep the call is. Reduce before you materialize — at any depth.
249
+
250
+ **That is a statement about the object, not about its report.** *Holding* a
251
+ range costs nothing; *returning* one renders its values as a table, capped, with
252
+ real A1 row and column labels — and that report is the read. So "a range is a
253
+ reference, not its contents" is the cost model talking, never a reason to reach
254
+ past `wb.getRange(a1)` for the values it is about to show you.
255
+
256
+ Every subject the engine can describe, the exact line that produces it, and what
257
+ each report carries is **one table** — *Orientation* in
258
+ [reading](references/reading.md). That table is the read surface; this file is
259
+ the order to take it in.
260
+
261
+ ## Opening and saving
262
+
263
+ | | Open | Save |
264
+ |---|---|---|
265
+ | **CLI** | the positional workbook (`sheetxl … book.xlsx`); omit it for a blank workbook — a calculator | `--save` writes back to the workbook that was opened; a different destination is `--out <file>`. `--save` with no workbook is an error |
266
+ | **MCP** | the session from the handshake, `session_create` for a sandbox, or a fork of either | every `run` commits; `session_save` persists to disk |
267
+
268
+ Format is the extension: prefer **`.sxl`** for working copies and pipelines;
269
+ deliver `.xlsx` when Excel itself will open the file.
270
+
271
+ ## run — the context and the two forms
272
+
273
+ Every run, on either transport, has exactly these five variables in scope — and
274
+ nothing else (in particular, **no `console`**):
275
+
276
+ | | What it is |
277
+ |---|---|
278
+ | `wb` | the workbook — from the workbook argument (CLI) / the session (MCP), or blank when there is neither |
279
+ | `log` / `warn` / `error` | output channels — use these, never `console.log` |
280
+ | `args` | arguments forwarded to the run (CLI: everything after `--`; MCP: the `args` object) |
281
+
282
+ The channels take an argument list, like `console.log`, and **any argument may be
283
+ a value**: `log(range.getStats())` renders the stats report, the same one
284
+ returning it would produce. `args` reads the same on both transports: `--region
285
+ EU` and `{ region: 'EU' }` are both `args.region`.
286
+
287
+ **Where the source comes from** is yours to state: a string via `-e "<code>"` or
288
+ piped on stdin (CLI) / `code` (MCP); a file via `sheetxl -f <script.ts>` (CLI) /
289
+ `path` (MCP). Code is never a positional on the CLI — the positional is the
290
+ workbook. **Pass code you wrote as a string; never write a scratch file just to
291
+ have a path** — what a file is for is in [scripting](references/scripting.md).
292
+
293
+ **On PowerShell, pipe a here-string to stdin — do not use `-e`.** Inside double
294
+ quotes PowerShell expands `$` and a backtick, so `$B$2` silently becomes empty
295
+ text and the mangled code still exits 0. And spreadsheet code is full of the
296
+ characters that break the quoting itself: an inner `"…"` ends the outer string,
297
+ after which a sheet qualifier (`'Sheet'!H14`) meets `!` as an operator and the
298
+ command dies at parse time — `Unexpected token '!H14'`, before `sheetxl` ever
299
+ runs. A single-quoted here-string is literal end to end, so nothing is rewritten
300
+ and nothing has to be escaped:
301
+
302
+ ```powershell
303
+ @'
304
+ wb.getRange('Sheet1!H14:H25').getStats()
305
+ '@ | sheetxl book.xlsx
306
+ ```
307
+
308
+ **What the source means** is decided by the code itself, not by how it arrived:
309
+
310
+ | Form | When | How it runs |
311
+ |---|---|---|
312
+ | **snippet** | no default export | runs *inside* the context (each member an implicit global); async is implicit — **never write `await`**; the final expression is the result |
313
+ | **script** | a module with a default export | *handed* the context (`{ wb, log, warn, error, args }`); its return value is the result |
314
+
315
+ So `code: "wb"` is a snippet and `code: "export default function main({ wb }) {…}"`
316
+ is a script — nothing to declare, and a file follows the same rule. Scripts are
317
+ for anything longer; both execute with no compile step. Contracts in full:
318
+ [scripting](references/scripting.md).
319
+
320
+ ## What comes back
321
+
322
+ Every run — either transport, either form — returns two things: **the log**
323
+ (whatever you passed to `log`/`warn`/`error`, in order), and **the result** (the
324
+ final expression, or a script's return value, rendered as markdown; void means no
325
+ result). **So describing anything is just returning it** — the subject you name
326
+ in code is the subject you get. A run that writes also reports **the delta** —
327
+ what its commit changed (`Changed:`, `Dependents:`, `Errors:` …) — on both
328
+ transports; a read-only run reports none:
329
+
330
+ ```bash
331
+ sheetxl -e "wb" book.xlsx # the workbook report
332
+ sheetxl -e "wb.evaluate('=NPV(0.08, 100, 200)')" # no workbook: blank = calculator
333
+ sheetxl -e "wb.getWorksheet('Assumptions').getRegions()" book.xlsx # where the blocks are
334
+ sheetxl -e "wb.getRange('B2').setValue('42%')" book.xlsx --save # set a value and save
335
+ ```
336
+
337
+ On MCP the same code goes in `code`, and there is no workbook argument: every tool routes by
338
+ `session_id`, which the handshake gave you. There is no `set` or `eval` command
339
+ to look for — `setValue` and `evaluate` above are each a one-line `run`
340
+ (`wb.evaluate('=…')` for the scalar alone, `createFormula` when you want
341
+ its value *and* the diagnostics beside it). `evaluate` returns a Promise: a
342
+ top-level line is awaited for you, but inside a loop write
343
+ `await wb.evaluate(…)`.
344
+
345
+ A probe that logs each finding and returns a tally is as normal a shape as
346
+ returning a subject. On the CLI, `--json` gives the same result as structured
347
+ JSON for piping.
348
+
349
+ ## Value encoding — one rule, both directions
350
+
351
+ A cell holds a value *and* a type; plain text would lose one of them. This
352
+ encoding carries both, losslessly, across every text boundary — values you set,
353
+ values you read back, on both transports. The rule: **a string you write from a
354
+ script is parsed the way Office Scripts' `setValue` parses it.** (Files such as
355
+ CSV, and a person typing in the grid, enter text exactly as typing into Excel
356
+ does.)
357
+
358
+ - `=SUM(A1:C1)` — leading `=` is a formula. A script-written formula takes no
359
+ number format from what it reads, so `=A1+1` over a date shows a serial and
360
+ `=TODAY()` a number. When the result is a date, time or percent, set the
361
+ format yourself (`getStyle().setNumberFormat('h:mm')`).
362
+ - `'42` — leading apostrophe **always** forces text (preserves leading zeros).
363
+ - `42%`, `$1,000`, `1/31/2026`, `TRUE` — the value, plus a matching number
364
+ format when the cell's current format is General.
365
+ - Non-string values (`0.42`, `true`) store as-is and never adjust the format.
366
+
367
+ A date whose ordering is ambiguous (`1/2/2026`) resolves by locale, like Excel —
368
+ write an unambiguous form when the distinction matters.
369
+
370
+ **The same rule holds on read** — what you read, written back, reproduces the
371
+ cell. Strings come back with the `'` prefix, which disambiguates at a glance:
372
+
373
+ - `10/23/95` — a number with a date format.
374
+ - `'10/23/95` — text that merely looks like a date.
375
+ - `'` alone — a cell holding an empty string: looks blank, is not empty.
376
+
377
+ More on writes (styling, batching, navigation): [writing](references/writing.md).
378
+
379
+ ## References
380
+
381
+ Load the reference matching the task — they live beside this file:
382
+
383
+ | Reference | Load when |
384
+ |---|---|
385
+ | [reading](references/reading.md) | understanding a sheet — **and the one map from subject to report** |
386
+ | [analysis](references/analysis.md) | auditing **or repairing** a workbook: the anomalies read, the shape sweep, the partition catalogue, sibling diffs, error tracing, the blast radius, proving the fix |
387
+ | [writing](references/writing.md) | changing a sheet **and verifying the change**: values, formulas, styling |
388
+ | [financial-models](references/financial-models.md) | building, completing **or auditing** a **financial model**: the standard lines, signs and units per model type (bond accounting, real estate, company models: ratios, cost of equity, the valuation bridge, NM values) |
389
+ | [charts](references/charts.md) | a chart: what it plots, inserting one, editing its type, data, title, legend, axes, series, labels, trendlines |
390
+ | [vector](references/vector.md) | computing over many cells: `IRange`, transforms, `setComputedValues` |
391
+ | [interactive](references/interactive.md) | a human has the workbook open: sessions, presence, guidance |
392
+ | [cli](references/cli.md) | terminal commands: `run`/`grep`/`info` flags, chaining, REPL |
393
+ | [sessions](references/sessions.md) | stateful work: commits, history, undo/restore, forking and what-ifs, saving to disk |
394
+ | [scripting](references/scripting.md) | writing the code you hand to `run`: snippet/script contracts, the typed API |
395
+ | [embedding](references/embedding.md) | building an application with SheetXL: the SDK as a library, embedding the engine or UI |
396
+ | [udf](references/udf.md) | authoring formula functions |
397
+ | [showcase](references/showcase.md) | a new user asks what SheetXL can do — demonstrate it |
398
+ | [setup](references/setup.md) | SheetXL is not installed and `info` cannot run |
package/package.json CHANGED
@@ -1,6 +1,34 @@
1
1
  {
2
2
  "name": "@sheetxl/skills",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.8.0-beta.14",
4
+ "description": "Agent-facing skills and reference documentation for SheetXL, version-matched to the engine that executes agent code.",
5
+ "homepage": "https://sheetxl.com",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "https://github.com/sheetxl/sheetxl.git"
9
+ },
10
+ "bugs": {
11
+ "url": "https://github.com/sheetxl/sheetxl/issues"
12
+ },
13
+ "license": "MIT",
14
+ "type": "module",
15
+ "exports": {
16
+ "./SKILL.md": "./SKILL.md",
17
+ "./references/*": "./references/*",
18
+ "./package.json": "./package.json"
19
+ },
20
+ "files": [
21
+ "SKILL.md",
22
+ "references",
23
+ "README.md",
24
+ "LICENSE.md"
25
+ ],
26
+ "keywords": [
27
+ "sheetxl",
28
+ "spreadsheet",
29
+ "agent",
30
+ "skills",
31
+ "mcp",
32
+ "llm"
33
+ ]
6
34
  }