@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.
@@ -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.