@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 +21 -0
- package/README.md +67 -2
- package/SKILL.md +398 -0
- package/package.json +31 -3
- package/references/analysis.md +532 -0
- package/references/charts.md +173 -0
- package/references/cli.md +287 -0
- package/references/embedding.md +74 -0
- package/references/financial-models.md +364 -0
- package/references/interactive.md +194 -0
- package/references/reading.md +708 -0
- package/references/scripting.md +198 -0
- package/references/sessions.md +225 -0
- package/references/setup.md +74 -0
- package/references/showcase.md +32 -0
- package/references/udf.md +400 -0
- package/references/vector.md +129 -0
- package/references/writing.md +368 -0
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
|
-
|
|
1
|
+
<!-- markdownlint-disable -->
|
|
2
|
+
# @sheetxl/skills
|
|
2
3
|
|
|
3
|
-
|
|
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.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
}
|