@sheetxl/skills 0.8.0-beta.16 → 0.8.0-beta.18
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/SKILL.md +17 -15
- package/package.json +1 -1
- package/references/analysis.md +2 -0
- package/references/reading.md +2 -1
- package/references/sessions.md +5 -4
package/SKILL.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sheetxl
|
|
3
|
-
version: 0.8.0-beta.
|
|
3
|
+
version: 0.8.0-beta.18
|
|
4
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
5
|
---
|
|
6
6
|
|
|
@@ -80,13 +80,12 @@ workflow below (modes, sessions, the handshake) does not apply to app code.
|
|
|
80
80
|
SheetXL's goal is your best result. Two rules:
|
|
81
81
|
|
|
82
82
|
- **SheetXL for the whole workbook.** Read, build, calculate, check and save
|
|
83
|
-
workbooks through SheetXL — values, formulas, formatting,
|
|
84
|
-
**openpyxl and pandas cannot compute**: openpyxl returns
|
|
85
|
-
string and writes workbooks with no calculated values, so any
|
|
86
|
-
or checks a *value* runs through SheetXL — including checking
|
|
87
|
-
not rebuild it in Python to compare.
|
|
88
|
-
|
|
89
|
-
it, it shipped: trust the types over this list. Never let openpyxl save over a
|
|
83
|
+
workbooks through SheetXL — values, formulas, formatting, tables, pivot tables,
|
|
84
|
+
charts and shapes. **openpyxl and pandas cannot compute**: openpyxl returns
|
|
85
|
+
`=SUM(B2:B4)` as a string and writes workbooks with no calculated values, so any
|
|
86
|
+
task that produces or checks a *value* runs through SheetXL — including checking
|
|
87
|
+
your own model; do not rebuild it in Python to compare. If the types have it, it
|
|
88
|
+
shipped: trust the types over any list here. Never let openpyxl save over a
|
|
90
89
|
SheetXL file — its round-trip drops what it does not model.
|
|
91
90
|
- **Formats**: `.xlsx`, `.sxl` and `.csv`. `.sxl` is SheetXL's native format — full
|
|
92
91
|
`.xlsx` parity, 50–500x smaller and significantly faster, so it is the right
|
|
@@ -118,14 +117,17 @@ undo, in-grid highlights, and asking the user a question.
|
|
|
118
117
|
|
|
119
118
|
The handshake leaves you in one of two modes:
|
|
120
119
|
|
|
121
|
-
**Attended** — a human has that workbook open
|
|
122
|
-
|
|
120
|
+
**Attended** — a human has that workbook open and sees every change the moment it
|
|
121
|
+
lands. When they are vague — "fix this", "B10 looks wrong" — they probably mean
|
|
123
122
|
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
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
On MCP that session is yours to use
|
|
128
|
-
|
|
123
|
+
on disk: what is on disk is stale the moment they have unsaved edits, and the
|
|
124
|
+
session is where their undo lives.
|
|
125
|
+
|
|
126
|
+
On MCP that session is yours to use: each `run` is one commit the user can step
|
|
127
|
+
through and revert from the agent panel at the top right of their grid, so make the
|
|
128
|
+
change, say what you changed, and `highlight` where — working with them is not a
|
|
129
|
+
reason for caution, and nothing about it needs a warning. Presence highlights and
|
|
130
|
+
in-grid prompts are yours too. **On the CLI there is no session to reach** — naming the workbook opens
|
|
129
131
|
the file on disk, which is the one thing you must not write back. So an attended CLI is a *read* surface:
|
|
130
132
|
query, calculate, report what you found, and let them make the change or hand the
|
|
131
133
|
work to the MCP server. See [interactive](references/interactive.md) for working
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sheetxl/skills",
|
|
3
|
-
"version": "0.8.0-beta.
|
|
3
|
+
"version": "0.8.0-beta.18",
|
|
4
4
|
"description": "Agent-facing skills and reference documentation for SheetXL, version-matched to the engine that executes agent code.",
|
|
5
5
|
"homepage": "https://sheetxl.com",
|
|
6
6
|
"repository": {
|
package/references/analysis.md
CHANGED
|
@@ -138,6 +138,8 @@ The checks, as the report names them:
|
|
|
138
138
|
| `typed number equals an unread input` | a number typed into a formula that equals an input cell nothing reads (`0.21` where Tax rate holds `0.21`) | the reference it replaced: the input the line names |
|
|
139
139
|
| `differs from its twin formulas` | formulas of the same shape that divide by `12` here and `365` there, or add a term the others take away | which side the business meant; the line names a twin |
|
|
140
140
|
| `off the scale of its format` | a typed percent a hundred times its siblings (`30` for 30%) | the unit it was typed in |
|
|
141
|
+
| `input nothing reads` | a typed number beside a label that no formula on any sheet reads (`Tax rate 21%` with no tax line) | in a model being built, the item still to build; in a finished one, a dead assumption or a formula that typed its value |
|
|
142
|
+
| `gap in a labeled row` | a labeled row empty where the rows above and below are filled, or empty in some of their columns | the line left out, or its missing period; `label font differs` marks a heading, which is empty by design |
|
|
141
143
|
| `constant` (the `Constants` section) | a constant typed into a formula, with its uses of the workbook's | a constant typed once where the model types another everywhere |
|
|
142
144
|
| `<layer> format break` | an authored font, fill, number format or alignment thin against its run | with `also changes`, structure; alone, a cell someone touched |
|
|
143
145
|
| `<part> format is another role's` | a link, same-sheet reference or calculation colored as the sheet colors another role | the color convention, per sheet: the majority is the rule |
|
package/references/reading.md
CHANGED
|
@@ -50,6 +50,7 @@ This is the whole read surface. Nothing below adds a call; it explains these.
|
|
|
50
50
|
| defined names | `wb.getNames()` · `sheet.getNames()` for one sheet's view · `.getByName('TaxRate')` for one | the roster: target, dependents, validity — broken first, then load-bearing. One name renders as a formula report |
|
|
51
51
|
| table | `sheet.getTables().getByName('Sales')` · `range.getTables()` for the ones a range touches | one table — its range, header, style and columns. The **collection** does not render; the sheet report's `Tables` section is the listing |
|
|
52
52
|
| conditional format | `range.getConditionalFormats()` | one rule — its anchor, evaluation order, predicate (or color scale / data bar / icon set) and the format it paints |
|
|
53
|
+
| sparklines | `range.getSparklineGroups()` · `cell.getSparkline()` · `range.getRegions('sparklines')` | a small chart drawn over a cell, not its value — its cell is usually **empty**. A group shares one type and set of marks; `group.getRanges()` are its cells, `group.getDataRanges()` the cells each range draws. The cell report states `Sparkline: line of A3:E3 · group F2:F4 · high, low`; the sheet report has a `Sparkline` section. That section, `Conditionals` and `DataValidations` list over the whole sheet: a layer over empty cells is outside the used range, and is still reported |
|
|
53
54
|
| data validation | `range.getDataValidations()` | one rule — its anchor, predicate, **the values a list admits**, whether blanks pass, and whether a bad entry is refused or merely flagged |
|
|
54
55
|
| protection | `sheet.getProtection()` · `wb.getProtection()` · `sheet.getProtectedRanges()` for the unlocked ranges | whether it is locked (and behind a password), and the operations it still **allows** — anything not listed is refused. Reported only where it is in force: a protected sheet is marked `(protected)` and carries a `protected` line on the workbook report, a `Protection` section on its own (the editable regions, each with why), a `Protection:` first line on a range report and an `Editable:` fact on a cell. An unprotected sheet says nothing (`writing.md` §"Protected sheets") |
|
|
55
56
|
| movable | `sheet.getMovables().getItems()` · `range.getMovables()` for the ones over a range · `{ type: 'chart' }` to filter | the floating layer — pictures, charts, shapes, slicers. One movable renders its name, type, preset, text, alt text, anchor and bounds — and for a chart its type, title, series and axes: the ranges it plots (`chart.getSeries()` states each as a formula), and the axis titles, which are often the only place units are written down. The listing is the sheet report's per-type sections — `Charts`, `Shapes`, `Pictures`, `Slicers` |
|
|
@@ -412,7 +413,7 @@ features at once is the cross-product, see above):
|
|
|
412
413
|
| audit | `anomalies` | what breaks the pattern around it? — derived from the other partitions, never authored; a region is a run of cells with the same finding and evidence |
|
|
413
414
|
|
|
414
415
|
Outside the categories: **`contentful`** (the default — contiguous blocks of data),
|
|
415
|
-
`merge`, `dataValidations`, `hyperlink`, `comments`, and `unlock` — the cells that
|
|
416
|
+
`merge`, `dataValidations`, `hyperlink`, `comments`, `sparkline`, and `unlock` — the cells that
|
|
416
417
|
still take a write on a protected sheet. `unlock` has no section on a sheet report:
|
|
417
418
|
it is the body of the `Protection` section, which prints only when the sheet is
|
|
418
419
|
protected.
|
package/references/sessions.md
CHANGED
|
@@ -173,10 +173,11 @@ Both forms:
|
|
|
173
173
|
### Attended sessions
|
|
174
174
|
|
|
175
175
|
The read tools, `run`, `session_revert`, `session_restore`, and the human-loop
|
|
176
|
-
tools all work against an attended session — edits
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
176
|
+
tools all work against an attended session — edits land in the user's grid the
|
|
177
|
+
moment they commit, and the user reviews and reverts them from the agent panel at
|
|
178
|
+
the top right of the grid, so there is nothing to warn them about. Because the
|
|
179
|
+
user may also be editing, pass `original_commit_id` on writes so a concurrent
|
|
180
|
+
edit is caught as `drift` rather than silently overwritten. Never open or close attended sessions;
|
|
180
181
|
the UI owns their lifecycle. The full attended-mode rules are `interactive.md`.
|
|
181
182
|
|
|
182
183
|
## Linking to cells (attended sessions only)
|