@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
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: scripting
|
|
3
|
+
description: "Writing SheetXL scripting code — the code you hand to `run` on either transport: runner scripts and inline snippets against the ambient SheetXL API; the typed API reference. Triggers on: script, snippet, ScriptContext, SheetXL namespace, default export, types, .d.ts, macro."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Scripting — The Code You Hand to `run`
|
|
7
|
+
|
|
8
|
+
> Part of the SheetXL skill suite. See the root `SKILL.md` for routing.
|
|
9
|
+
|
|
10
|
+
**In this file:** Scripts (default export) · Inline snippets (no default
|
|
11
|
+
export) · The typed API is the map · When scripting cannot
|
|
12
|
+
|
|
13
|
+
One dialect, two transports: the same TypeScript executes via the CLI
|
|
14
|
+
(`sheetxl`) and the MCP macro tool, written against the ambient `SheetXL`
|
|
15
|
+
API — no imports. This is **scripting**, and it is the normal way agents write
|
|
16
|
+
SheetXL code. The environment is pre-provisioned: file IO is already installed,
|
|
17
|
+
the workbook is handed to you, and saving belongs to the invocation (`--save`
|
|
18
|
+
on the CLI; commits on a session) — your code never opens, saves, or constructs
|
|
19
|
+
a workbook. When a task exceeds what scripting can express, **drop to the SDK**
|
|
20
|
+
(last section).
|
|
21
|
+
|
|
22
|
+
Both run forms share **one context** — these five members and nothing else (in
|
|
23
|
+
particular, no `console`). The relationship is simple: a script is *handed* the
|
|
24
|
+
context; a snippet runs *inside* it, every member an implicit global.
|
|
25
|
+
|
|
26
|
+
| Context member | What it is |
|
|
27
|
+
|---|---|
|
|
28
|
+
| `wb` | the workbook — from the workbook argument (CLI) / the session (MCP), or blank when there is neither |
|
|
29
|
+
| `log` / `warn` / `error` | output channels — use these, never `console.log` |
|
|
30
|
+
| `args` | arguments forwarded to the run (CLI: everything after `--`; MCP: the `args` object) |
|
|
31
|
+
|
|
32
|
+
`log` is not a debug afterthought — it is the reporting channel. It takes an
|
|
33
|
+
argument list like `console.log` (`log('rows:', n, 'ok', true)`), and any of
|
|
34
|
+
those arguments may be a **value, not just a string**: `log(range.getStats())`
|
|
35
|
+
renders the stats exactly as returning them would. In query-shaped runs (scans,
|
|
36
|
+
audits, anything with per-item findings) stream the findings with `log` as you
|
|
37
|
+
go and let the return value carry the tally — a probe's logs *are* its output.
|
|
38
|
+
`warn`/`error` are diagnostics rather than findings, and travel separately
|
|
39
|
+
(stderr on the CLI).
|
|
40
|
+
|
|
41
|
+
`args` reads the same on both transports — `--region EU` on the CLI and
|
|
42
|
+
`{ region: 'EU' }` on MCP are both `args.region`, so a parameterized script
|
|
43
|
+
moves between them without an edit. The CLI additionally exposes the raw tail
|
|
44
|
+
(`args.raw`), the parsed flags (`args.kv`) and the positionals (`args._`).
|
|
45
|
+
|
|
46
|
+
## Scripts (default export)
|
|
47
|
+
|
|
48
|
+
For anything longer than a few lines. A module with a default export is a
|
|
49
|
+
script; it is **handed the context as its one parameter** and destructures what
|
|
50
|
+
it needs:
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
export default function main({ wb, log }: SheetXL.IScript.ScriptContext): void {
|
|
54
|
+
wb.getWorksheet().getRange('B2').setValue(99);
|
|
55
|
+
log('Updated B2');
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
That entry is portable: the same file runs on the CLI (`sheetxl -f script.ts`)
|
|
60
|
+
and as an MCP macro, because both hand it the same five members. Write this form
|
|
61
|
+
unless you need the exception below.
|
|
62
|
+
|
|
63
|
+
**The exception — a macro that wants "the selected" something.** A macro may
|
|
64
|
+
take its target as the *first* parameter and the context second, which is how it
|
|
65
|
+
asks the runtime for the current sheet or range rather than the whole workbook:
|
|
66
|
+
|
|
67
|
+
```typescript
|
|
68
|
+
export default function main(sheet: SheetXL.IWorksheet, ctx: SheetXL.IScript.ScriptContext): void {
|
|
69
|
+
ctx.log('running against', sheet.getName()); // the SELECTED sheet
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Valid targets are `IWorkbook`, `IWorksheet`, `ICellRanges` and `ICellRange`. This
|
|
74
|
+
form is macro-only — the CLI runner passes one argument, so a two-parameter
|
|
75
|
+
entry leaves its second undefined there.
|
|
76
|
+
|
|
77
|
+
- **Name the default export** (anonymous fails to compile).
|
|
78
|
+
- **Annotate the parameter and the return type** (untyped fails to compile).
|
|
79
|
+
- The `SheetXL` API is **ambient and a runtime global** — types, enums, and
|
|
80
|
+
statics all reachable (e.g. `SheetXL.ISheet.Visibility.Visible`); no
|
|
81
|
+
`import` statements, ever.
|
|
82
|
+
- Async is fine: `async function main(...): Promise<...>`.
|
|
83
|
+
- **The return value is the run result** — exactly like a snippet's final
|
|
84
|
+
expression, and **every result renders**: scalars via the value-encoding
|
|
85
|
+
rules, ranges/stats/formulas via their own shapes (`--json` on the CLI when
|
|
86
|
+
you need to pipe it). Return nothing when there is nothing to report — and
|
|
87
|
+
stream per-item findings with `log` as you go.
|
|
88
|
+
- Where the workbook comes from and goes: the workbook argument / `--save`
|
|
89
|
+
(CLI), the session and its commit (MCP). Never `WorkbookIO`, never
|
|
90
|
+
`new Workbook()`.
|
|
91
|
+
|
|
92
|
+
**A script does not need to live in a file.** Pass the whole module text as a
|
|
93
|
+
string — `code` on MCP, `-e` or stdin on the CLI. Code you just wrote never
|
|
94
|
+
earns a file: writing one to have a path to point at costs a round trip and
|
|
95
|
+
leaves litter, and a failed compile answers with positioned diagnostics either
|
|
96
|
+
way, so the run is also the typecheck.
|
|
97
|
+
|
|
98
|
+
A **file** (`path` on MCP, `-f` on the CLI) is for a script with a life beyond
|
|
99
|
+
this turn — human-authored, checked into the repo, reused across sessions — or,
|
|
100
|
+
in attended mode, when the user should be able to *read* what is about to run
|
|
101
|
+
against their live workbook. `sheetxl compile` typechecks one without executing
|
|
102
|
+
it, which makes it a CI gate rather than a prerequisite.
|
|
103
|
+
|
|
104
|
+
## Inline snippets (no default export)
|
|
105
|
+
|
|
106
|
+
For one-liners and short transforms. The snippet runs inside the context — same
|
|
107
|
+
names, no destructuring. **Async is implicit at the top level**: each top-level
|
|
108
|
+
statement that yields a promise is awaited automatically, so a top-level line
|
|
109
|
+
never needs `await`. The final expression's (resolved) value is the result:
|
|
110
|
+
|
|
111
|
+
```typescript
|
|
112
|
+
wb.getWorksheet().evaluate('=SUM(A:A)')
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Only top-level statements are awaited for you. A promise made **inside** a loop,
|
|
116
|
+
a callback or a larger expression is still a promise — `evaluate` returns one —
|
|
117
|
+
so write `await` there:
|
|
118
|
+
|
|
119
|
+
```typescript
|
|
120
|
+
const sheet = wb.getWorksheet();
|
|
121
|
+
for (let r = 2; r <= 10; r++) {
|
|
122
|
+
const serial = await wb.evaluate(`=DATEVALUE(A${r})`); // without await: a Promise
|
|
123
|
+
sheet.getRange(`B${r}`).setValue(serial);
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
```typescript
|
|
128
|
+
const sheet = wb.getWorksheet();
|
|
129
|
+
sheet.getRange('B2').setValue('42%');
|
|
130
|
+
log('B2 updated');
|
|
131
|
+
sheet.getRange('B2').getValue() // final expression → result
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Statements, not lines — the same snippet is one shell-friendly `-e` argument:
|
|
135
|
+
|
|
136
|
+
```typescript
|
|
137
|
+
const sheet = wb.getWorksheet();sheet.getRange('B2').setValue('42%');log('B2 updated');sheet.getRange('B2').getValue()
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
End on an expression — that is the result. A snippet ending in a declaration or
|
|
141
|
+
loop returns nothing.
|
|
142
|
+
|
|
143
|
+
"Top-level" is literal, and the separation is a parser's: the snippet is parsed
|
|
144
|
+
as TypeScript, so semicolons are optional here exactly as they are in any file
|
|
145
|
+
and the same ASI rules apply. The implicit await reaches every top-level
|
|
146
|
+
statement — including each declarator of a `const a = …, b = …` — but not a
|
|
147
|
+
statement nested inside a loop or block. If a body needs awaiting inside control
|
|
148
|
+
flow, that is the signal it has outgrown a snippet — write it as a script, where
|
|
149
|
+
`await` is yours to place.
|
|
150
|
+
|
|
151
|
+
Need a blank workbook? Omit the workbook argument; do not construct one.
|
|
152
|
+
|
|
153
|
+
The form is decided by the code itself — a default export makes it a script;
|
|
154
|
+
anything else runs as a snippet. Where the source comes from (CLI file, `-e`,
|
|
155
|
+
stdin; MCP `code` or `path`) never changes what it means.
|
|
156
|
+
|
|
157
|
+
## The typed API is the map
|
|
158
|
+
|
|
159
|
+
The shipped type definitions are the authoritative API surface — if it is not in
|
|
160
|
+
the types, it does not exist. Look a name up instead of guessing it:
|
|
161
|
+
|
|
162
|
+
- **`api`** — `sheetxl api ICellRange` on the CLI, the `api` tool over MCP, `.api` in a
|
|
163
|
+
session. A type lists what you can call on it, one line per member (signature and
|
|
164
|
+
summary); `api ICellRange.setValues` prints that member's full documentation;
|
|
165
|
+
`api merge` searches type and member names; bare `api` lists where to start. This is
|
|
166
|
+
the cheap read — reach for it before writing a call you have not made before.
|
|
167
|
+
- **`scripting.d.ts`** — the same surface as one file, every declaration with its full
|
|
168
|
+
documentation (`sheetxl info` prints the path). It is what a script is type-checked
|
|
169
|
+
against, and it names types the way a script writes them: `SheetXL.ICellRange`, never a
|
|
170
|
+
bare `ICellRange`. It is large and mostly documentation — grep it for a name and read
|
|
171
|
+
around the hit; do not read it whole.
|
|
172
|
+
- **`scripting-api.json`**, beside it — the index `api` answers from, one line per
|
|
173
|
+
member. For when you have file access and nothing else.
|
|
174
|
+
- Docs: https://www.sheetxl.com/docs
|
|
175
|
+
|
|
176
|
+
The guesses that still fail, and the call that exists:
|
|
177
|
+
|
|
178
|
+
| Guessed | Exists |
|
|
179
|
+
|---|---|
|
|
180
|
+
| `wb.getSheets().getAt(0)` · `.getItems()` | `getSheets()` returns a plain array. By index: `wb.getWorksheetAt(0)`; by name: `wb.getWorksheet('Name')`; all grids: `wb.getWorksheets().getItems()` |
|
|
181
|
+
| `cell.setValue(…)` · `cell.setStyle(…)` | `ICell` is a read lens. Writes go through the range: `range.setValue`, `range.getStyle()` |
|
|
182
|
+
| `range.setValues(42)` | `setValues` takes a 2-D array; one value is `setValue(42)` |
|
|
183
|
+
| `cell.getFormula().replace(…)` | `getFormula()` is an `IFormula` object; the text is `cell.getFormulaText()`, or `range.getFormulas()` for a block |
|
|
184
|
+
|
|
185
|
+
Names from other spreadsheet APIs (Office Scripts, Apps Script) often still run as
|
|
186
|
+
deprecated aliases, but `api` does not list them. Write the name `api` documents.
|
|
187
|
+
|
|
188
|
+
For sheet interaction patterns see `reading.md` / `writing.md`; for custom
|
|
189
|
+
formula functions see `udf.md`.
|
|
190
|
+
|
|
191
|
+
## When scripting cannot
|
|
192
|
+
|
|
193
|
+
Some tasks exceed the run context — e.g. operating on two workbooks at once.
|
|
194
|
+
The next rung is a standalone program written against `@sheetxl/sdk` with real
|
|
195
|
+
imports: see [embedding](embedding.md). Building the user's application is the same path.
|
|
196
|
+
Under `run`, none of that applies — the workbook is handed to you, and a blank
|
|
197
|
+
one is what you get by omitting the workbook argument; constructing your own is
|
|
198
|
+
basically never right.
|
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sessions
|
|
3
|
+
description: "SheetXL sessions — stateful spreadsheet work: workbooks kept in memory between calls, per-run commits with undo/restore, commit history, forking and the what-if workflow (experiment on a copy, verify, then apply), saving to disk, and the audited write path. Use whenever the SheetXL MCP server is connected. Triggers on: session, list_sessions, list_commits, session_create, session_save, session_close, commit, revert, restore, drift, fork, sandbox, attended session, what-if, experiment, try it out, compare scenarios."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Sessions — Stateful Spreadsheet Work
|
|
7
|
+
|
|
8
|
+
> Part of the SheetXL skill suite. See the root `SKILL.md` for routing;
|
|
9
|
+
> `interactive.md` for the human-loop tools (`highlight`, `prompt`).
|
|
10
|
+
|
|
11
|
+
**In this file:** Start here · Tools · Discovery · History — `list_commits` ·
|
|
12
|
+
Working in a sandbox · Experiments and what-ifs — fork first · The write path —
|
|
13
|
+
`run` · Linking to cells · Agent operating rules · Reading a session
|
|
14
|
+
|
|
15
|
+
The MCP server gives you live read/write access to spreadsheet **sessions**. A
|
|
16
|
+
session is a workbook plus where its engine lives:
|
|
17
|
+
|
|
18
|
+
- **sandbox** — owned by the server, headless, in-process. You create these on demand.
|
|
19
|
+
- **attended** — owned by a client UI (a VS Code workbook), reached over the relay.
|
|
20
|
+
|
|
21
|
+
**Scripting is the API here — the short tool list is deliberate.** The server
|
|
22
|
+
exposes discovery and session management as tools; every write goes through
|
|
23
|
+
`run`, which executes SDK TypeScript you author against the live workbook.
|
|
24
|
+
Writing code is the primary, fully supported path — not a fallback for missing
|
|
25
|
+
tools.
|
|
26
|
+
|
|
27
|
+
## Start here — before doing anything else
|
|
28
|
+
|
|
29
|
+
1. **Workbook files come through these tools, not the file system.** Do NOT
|
|
30
|
+
read `.xlsx` or `.sxl` from disk — they are binary. (`.csv` is plain text:
|
|
31
|
+
any tool may handle it; come through these tools when formulas, types, or
|
|
32
|
+
structure matter.)
|
|
33
|
+
2. **Know your sessions.** The `info` handshake (root `SKILL.md`) already seeds
|
|
34
|
+
the open sessions and connected users; call `list_sessions` to refresh that
|
|
35
|
+
view at any point. Every tool requires a `session_id` — pass the id of the
|
|
36
|
+
session you mean; there is no default, and a call without one is refused
|
|
37
|
+
rather than routed to whatever the user has open. An `attended`
|
|
38
|
+
session means a user has that workbook open right now — when they reference
|
|
39
|
+
a cell without naming a file ("what's wrong with B10?"), they mean the
|
|
40
|
+
active attended session, never a file on disk.
|
|
41
|
+
3. **Never open or close attended sessions.** The client UI owns those. To work
|
|
42
|
+
in isolation, create your own sandbox with `session_create`.
|
|
43
|
+
|
|
44
|
+
## Tools
|
|
45
|
+
|
|
46
|
+
| Tool | Purpose |
|
|
47
|
+
|---|---|
|
|
48
|
+
| `info` | The session-start handshake: environment, sessions, users. Read-only. |
|
|
49
|
+
| `grep` | Find cells by content or pattern. |
|
|
50
|
+
| `run` | Execute SDK TypeScript as one undoable commit — the write path, and every structured read (return the subject and it renders). |
|
|
51
|
+
| `list_sessions` | List all sessions (sandbox + attended). |
|
|
52
|
+
| `list_commits` | A session's history: who changed what, when — the source of `commitId`s. |
|
|
53
|
+
| `session_create` | Create a sandbox: empty, from a `path`, or a fork of a `source` session. |
|
|
54
|
+
| `session_close` | Dispose a sandbox you no longer need (sandboxes only). |
|
|
55
|
+
| `session_revert` | Undo a specific change by its `commitId`. |
|
|
56
|
+
| `session_restore` | Move a session back to a previous commit point. |
|
|
57
|
+
| `session_save` | Write a session to disk. No `path` (or its own file) saves back to the file it was opened from; another `path` is a Save As, which a sandbox then belongs to. `overwrite` is needed only to replace a different existing file. Relative paths resolve against the workspace; format guidance is in the root `SKILL.md`. |
|
|
58
|
+
| `highlight` / `prompt` | Human-loop tools — see `interactive.md`. |
|
|
59
|
+
|
|
60
|
+
The feature vocabulary — what `getRegions` / `getCounts` take inside `run` — is
|
|
61
|
+
documented in `reading.md`.
|
|
62
|
+
|
|
63
|
+
## Discovery
|
|
64
|
+
|
|
65
|
+
`list_sessions` returns every open session. Each entry has:
|
|
66
|
+
|
|
67
|
+
- `id` — pass this as `session_id`.
|
|
68
|
+
- `kind` — `sandbox` (yours, writable now) or `attended` (a client-UI workbook).
|
|
69
|
+
- `origin` — `blank`, `file`, or `fork`; `forked from` names the source session,
|
|
70
|
+
and a fork is named after what it forked (`Budget.xlsx (fork)`).
|
|
71
|
+
- `view` or `headless` — whether a grid is showing it. `highlight` and `prompt`
|
|
72
|
+
only do anything on a session with a view.
|
|
73
|
+
- `path` — the workbook's file, when known.
|
|
74
|
+
- `opened … ago` — the session's **history epoch**: when its workbook was
|
|
75
|
+
(re)loaded. Commit ids from before this moment are gone.
|
|
76
|
+
- `head` — the current commit id (pass as `original_commit_id` for a guarded write).
|
|
77
|
+
|
|
78
|
+
If a chat context chip is attached (value `<id>:<address>`), the part before `:`
|
|
79
|
+
is an attended `session_id`.
|
|
80
|
+
|
|
81
|
+
**Attended ids are stable; histories are not.** An attended session's id is
|
|
82
|
+
derived from its file path, so the same file has the same id across editor
|
|
83
|
+
reloads and restarts — an id you learned earlier keeps working. What does NOT
|
|
84
|
+
survive a reload is the workbook's commit/undo history: the `opened` stamp
|
|
85
|
+
resets, and commit ids from before it are dead. Sandboxes are the perishable
|
|
86
|
+
kind — they live only as long as the server process.
|
|
87
|
+
|
|
88
|
+
**You are told when any of this happens.** Changes you did not make — the user
|
|
89
|
+
opening, closing, or reloading a workbook — are announced at the top of your
|
|
90
|
+
next tool result. `list_sessions` also reports **recently closed** sessions in
|
|
91
|
+
their own section: not usable, listed so an id you are holding resolves to a
|
|
92
|
+
reason rather than to silence. Passing a dead id to any tool gives you the same
|
|
93
|
+
explanation.
|
|
94
|
+
|
|
95
|
+
## History — `list_commits`
|
|
96
|
+
|
|
97
|
+
`list_commits(session_id, limit?)` returns the session's commit log, newest
|
|
98
|
+
first — `commitId`, description, who wrote it (or unattributed), timestamp. It
|
|
99
|
+
is how you obtain a `commitId` for `session_revert` / `session_restore`.
|
|
100
|
+
|
|
101
|
+
**Read it in order, whole.** Resuming a session, or working alongside a user,
|
|
102
|
+
start here: *"three commits since you last looked, two of them not mine"* is the
|
|
103
|
+
signal that your assumptions about the workbook may be stale — re-read before
|
|
104
|
+
writing. The order matters as much as the authors: a change of theirs that
|
|
105
|
+
landed after yours may have moved what you wrote.
|
|
106
|
+
|
|
107
|
+
## Working in a sandbox
|
|
108
|
+
|
|
109
|
+
1. `session_create` with no arguments (empty workbook), a `path` (open from
|
|
110
|
+
disk), or a `source` (clone another session — including an attended one, for
|
|
111
|
+
safe experiments). The origin (`blank` | `file` | `fork`) is inferred from
|
|
112
|
+
which you pass. Returns the new `session_id`.
|
|
113
|
+
2. Make changes with `run` (below).
|
|
114
|
+
3. `list_commits` to read the history; `session_revert` / `session_restore` to undo.
|
|
115
|
+
4. `session_save` to persist the result to disk — commits live in the session;
|
|
116
|
+
the file only changes when you save.
|
|
117
|
+
5. `session_close` when done (frees the in-memory workbook). Only sandboxes can
|
|
118
|
+
be closed.
|
|
119
|
+
|
|
120
|
+
## Experiments and what-ifs — fork first
|
|
121
|
+
|
|
122
|
+
Any work you are not yet sure you want is done on a **fork**, not on the
|
|
123
|
+
original: a risky multi-step restructure, "what happens to the totals if this
|
|
124
|
+
assumption changes", comparing two approaches before committing to one. A fork
|
|
125
|
+
is an in-memory clone — cheap to make, free to discard — and the original never
|
|
126
|
+
sees the experiment.
|
|
127
|
+
|
|
128
|
+
The loop:
|
|
129
|
+
|
|
130
|
+
1. **Fork** — `session_create` with `origin: "fork"` + `source: <session_id>`.
|
|
131
|
+
Works on any session, including an attended one.
|
|
132
|
+
2. **Try** — make the changes with `run` against the fork.
|
|
133
|
+
3. **Verify** — read the results back off the fork; compare against the original
|
|
134
|
+
by running the same read on both sessions ("original says X, the fork says Y"
|
|
135
|
+
is one `run` per session).
|
|
136
|
+
4. **Apply or discard** — apply the verified change to the original as a fresh
|
|
137
|
+
`run` (on an attended session, guarded by `original_commit_id` — the user may
|
|
138
|
+
have edited meanwhile); or just `session_close` the fork and nothing ever
|
|
139
|
+
happened.
|
|
140
|
+
|
|
141
|
+
Do **not** re-play the experiment on the original by saving the fork over its
|
|
142
|
+
file — the fork's history includes the dead ends, and on an attended session the
|
|
143
|
+
file is not the workbook (the UI's unsaved state is). The fork is where you
|
|
144
|
+
*learn* the change; the original is where you *make* it, once, cleanly.
|
|
145
|
+
|
|
146
|
+
Two degenerate forms are already safe without a fork: a `session_revert` after a
|
|
147
|
+
single bad commit (every `run` is undoable), and a pure read — reading never
|
|
148
|
+
needs isolation. And `createFormula` is the zero-cost end of the same
|
|
149
|
+
spectrum: a one-formula what-if that commits nothing (`analysis.md`).
|
|
150
|
+
|
|
151
|
+
On the **CLI** there are no forks; the same discipline is a file copy — work on a
|
|
152
|
+
duplicate, or simply withhold `--save` until the run's output proves the change,
|
|
153
|
+
since nothing touches disk without it.
|
|
154
|
+
|
|
155
|
+
## The write path — `run`
|
|
156
|
+
|
|
157
|
+
The source comes from exactly one of two parameters — never both: `code` (the
|
|
158
|
+
source as a string) or `path` (a local file this server reads). Which to use, and
|
|
159
|
+
what the code means once it arrives — snippet versus script, the context, the
|
|
160
|
+
ambient `SheetXL` API — is `scripting.md`. Either form executes as a single
|
|
161
|
+
undoable commit against the session.
|
|
162
|
+
|
|
163
|
+
Both forms:
|
|
164
|
+
|
|
165
|
+
- Always pass a `description` — it becomes the undo/commit label.
|
|
166
|
+
- On success you get a `commitId`; use it with `session_revert`.
|
|
167
|
+
- To guard against concurrent edits, pass `original_commit_id` (the session
|
|
168
|
+
`head`); if the session changed since, the write is rejected with
|
|
169
|
+
`status: "drift"` — re-read and retry.
|
|
170
|
+
- If compilation fails, the report lists positioned diagnostics with a `fix`
|
|
171
|
+
for each — apply them and call `run` again.
|
|
172
|
+
|
|
173
|
+
### Attended sessions
|
|
174
|
+
|
|
175
|
+
The read tools, `run`, `session_revert`, `session_restore`, and the human-loop
|
|
176
|
+
tools all work against an attended session — edits run against the live workbook and
|
|
177
|
+
appear immediately in the UI. Because the user may also be editing, prefer
|
|
178
|
+
passing `original_commit_id` on writes so a concurrent edit is caught as
|
|
179
|
+
`drift` rather than silently overwritten. Never open or close attended sessions;
|
|
180
|
+
the UI owns their lifecycle. The full attended-mode rules are `interactive.md`.
|
|
181
|
+
|
|
182
|
+
## Linking to cells (attended sessions only)
|
|
183
|
+
|
|
184
|
+
When you cite a cell or range that lives in an **attended** session, render it as a
|
|
185
|
+
clickable deep link so the user can jump straight to it. Clicking the link
|
|
186
|
+
reveals that workbook and selects the range in the grid.
|
|
187
|
+
|
|
188
|
+
Markdown form — link the address text to a `vscode://` URI:
|
|
189
|
+
|
|
190
|
+
```text
|
|
191
|
+
[Sheet1!B10](vscode://sheetxl.sheetxl-vscode/select?session=<session_id>&range=Sheet1!B10)
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
- `session` — the attended session's `id` (from `list_sessions`). Include it whenever
|
|
195
|
+
more than one workbook is open; if you omit it, the link targets the active one.
|
|
196
|
+
- `range` — a sheet-qualified address (`Sheet1!A1:B4`) or a named range. URL-encode
|
|
197
|
+
it (a space becomes `%20`, `!` may stay literal).
|
|
198
|
+
- The link text is yours — use the human-readable address (e.g. `Sheet1!B10` or
|
|
199
|
+
"the total"), not the URI.
|
|
200
|
+
|
|
201
|
+
Do **not** emit these links for **sandbox** sessions — they are headless and have
|
|
202
|
+
no grid to reveal. Prefer linking the specific cells you reference in prose
|
|
203
|
+
(totals, errors, the range you changed) rather than every address.
|
|
204
|
+
|
|
205
|
+
## Agent operating rules
|
|
206
|
+
|
|
207
|
+
- Do not perform arithmetic or computation on cell values yourself — the
|
|
208
|
+
calculation engine handles this correctly. To compute: write a formula
|
|
209
|
+
(e.g. `=SUM(A1:A10)`) or use the SDK via `run`, and let the engine evaluate.
|
|
210
|
+
- Use cell values to understand what the user sees and to write back what the
|
|
211
|
+
user would type. The value-encoding contract (the `'` prefix and friends) is
|
|
212
|
+
the root `SKILL.md` — it applies to every tool input and response carrying
|
|
213
|
+
cell data.
|
|
214
|
+
|
|
215
|
+
## Reading a session
|
|
216
|
+
|
|
217
|
+
Reading routes through two tools. `grep` takes an **A1-scoped** pattern search
|
|
218
|
+
(a range, `Sheet1!A1:D9`, or a bare sheet name for its used range); everything
|
|
219
|
+
else is `run`, where naming a subject in code *is* how you describe it. Which
|
|
220
|
+
subject answers which question is `reading.md`; the order to take them in is the
|
|
221
|
+
root `SKILL.md`.
|
|
222
|
+
|
|
223
|
+
Every response is self-describing — it names what it does *not* contain
|
|
224
|
+
(truncated, or a different lens available), so the next call is always obvious.
|
|
225
|
+
Elision is explicit; results are never silently truncated.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: setup
|
|
3
|
+
description: "Fallback install instructions for when SheetXL is not available and `sheetxl info` cannot run — bootstrap requirements (Node), per-client MCP registration, the VS Code extension, and skills installation. The primary setup path is always `npx -y sheetxl setup`; use this reference only when no SheetXL surface can run in this environment."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Setup — Fallback Instructions
|
|
7
|
+
|
|
8
|
+
> Part of the SheetXL skill suite. The **primary** setup path is dynamic:
|
|
9
|
+
> `npx -y sheetxl setup` detects the environment and converges it with consent at
|
|
10
|
+
> each step, and `npx -y sheetxl info` reports what is missing. Use this reference
|
|
11
|
+
> only when neither can run here (no shell, or no Node yet) — its job is to give
|
|
12
|
+
> the human the instructions to run elsewhere.
|
|
13
|
+
|
|
14
|
+
## Requirements
|
|
15
|
+
|
|
16
|
+
- **Node.js** (a current LTS release) with `npm`/`npx` on PATH — everything below
|
|
17
|
+
is delivered through npm.
|
|
18
|
+
|
|
19
|
+
## The one-command path (preferred)
|
|
20
|
+
|
|
21
|
+
Have the user run in any terminal:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npx -y sheetxl setup
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
It installs the skills, ensures the engine, registers the MCP server for detected
|
|
28
|
+
clients, and offers the VS Code extension — asking consent at each install
|
|
29
|
+
boundary. Re-running is always safe: already-converged steps are no-ops.
|
|
30
|
+
|
|
31
|
+
## Manual steps (when the one-command path is unavailable)
|
|
32
|
+
|
|
33
|
+
Each step is optional and independent. Confirm before installing anything into a
|
|
34
|
+
user's editor or client configuration.
|
|
35
|
+
|
|
36
|
+
**Skills** (ambient knowledge for any agent):
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
npx -y skills add sheetxl/skills -g --all
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
**Engine/CLI** (zero-install via npx, or global):
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
npx -y sheetxl info # zero-install: npx fetches and caches
|
|
46
|
+
npm install -g sheetxl # or: global install
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
**MCP server** (sessions, audited edits, undo — and human detection):
|
|
50
|
+
|
|
51
|
+
- Claude Code: `claude mcp add sheetxl -- npx -y sheetxl mcp`
|
|
52
|
+
- Other clients: add to the client's MCP configuration:
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{ "command": "npx", "args": ["-y", "sheetxl", "mcp"] }
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
- Newly registered servers usually attach at the next session — say so, and do
|
|
59
|
+
not claim the MCP tools until they are actually connected.
|
|
60
|
+
|
|
61
|
+
**VS Code extension** (human in the loop: attended sessions, live highlights,
|
|
62
|
+
prompts). Ask first — this installs software into their editor:
|
|
63
|
+
|
|
64
|
+
```bash
|
|
65
|
+
code --install-extension sheetxl.sheetxl-vscode
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
A running VS Code window needs a reload to activate it; if the `code` command is
|
|
69
|
+
not on PATH, point the user to the marketplace instead.
|
|
70
|
+
|
|
71
|
+
## If something fails
|
|
72
|
+
|
|
73
|
+
Run `npx -y sheetxl info` and report its diagnostic output. Do not fall back to
|
|
74
|
+
editing spreadsheet files with generic tools — `.xlsx` / `.sxl` are binary.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: showcase
|
|
3
|
+
description: "A user new to SheetXL asks what it can do — 'show me', 'tell me 3 interesting things', 'what is SheetXL good at'. Demonstrate with real output, never a capabilities list. Triggers on: what can SheetXL do, show me SheetXL, 3 interesting things, demo."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Showcase — Demonstrate, Don't Describe
|
|
7
|
+
|
|
8
|
+
> Part of the SheetXL skill suite. See the root `SKILL.md` for routing.
|
|
9
|
+
|
|
10
|
+
When a user has just installed SheetXL and asks what it can do, **show real output,
|
|
11
|
+
not a capabilities list**. The rule: **production, not fake** — real files, live
|
|
12
|
+
formulas, genuine recalculation. Never canned output or fabricated results; every
|
|
13
|
+
demonstration ends with an artifact the user can keep.
|
|
14
|
+
|
|
15
|
+
Pick three demonstrations matched to their context:
|
|
16
|
+
|
|
17
|
+
- **They have spreadsheet files nearby** → open one: summarize its structure,
|
|
18
|
+
surface any formula errors, offer to fix them with before/after error counts.
|
|
19
|
+
- **No files around** → build something real from scratch (a loan amortization or
|
|
20
|
+
budget model with live formulas), save it as `.xlsx`, and show a markdown
|
|
21
|
+
preview.
|
|
22
|
+
- **Show the engine** → evaluate a gnarly formula chain, then demonstrate a
|
|
23
|
+
what-if: change an input and read the recalculated results.
|
|
24
|
+
- **Mention, briefly**: `.sxl` (SheetXL's native format, 50–500x smaller than
|
|
25
|
+
xlsx), and — if the MCP server is connected — audited edits with undo.
|
|
26
|
+
|
|
27
|
+
Keep it concrete: each "interesting thing" ends with an artifact or output the
|
|
28
|
+
user can see, and an offer to go further with their own data.
|
|
29
|
+
|
|
30
|
+
Follow-ups usually come as real tasks ("fix this", "analyze my sheet") — handle
|
|
31
|
+
them like any other work from the root `SKILL.md`; this reference is only for the
|
|
32
|
+
show-me moment.
|