docs(skill): add no-bundle sigma-plugin skill (upload-source) + lint by guyathomas · Pull Request #69 · sigmacomputing/plugin

guyathomas · 2026-07-23T16:37:15Z

docs(skill): add no-bundle sigma-plugin skill (upload-source) + lint

Purpose

Adds the authoritative .claude/skills/sigma-plugin skill (+ lint-plugin.mjs) to
the SDK repo, instructing an agent how to create/develop/deploy/debug a Sigma custom
plugin against the no-bundle /v2/plugins model: upload a raw source tree
(sigcli plugins create / upload-source / pull-source), which Sigma transforms
(TS/JSX→JS, syntax-only) and serves as native ESM with an esm.sh import map — no
local build, no bundle upload.

This is the canonical model (aligns with mono-node #37265 "no-bundle upload →
transform → CDN serving" and the B3 work). It supersedes the earlier
add-claude-code-skill draft, which used the pre-built single-file upload-bundle
model we are not using.

What the skill covers

Scaffold a source tree (no vite-plugin-singlefile, no build-to-deploy).
Deploy via upload-source; recover via pull-source.
Schema-first design (enumerate real columns before configureEditorPanel), the
column-oriented element-data contract, and the ~25k-row cap.
The config-value-vs-key silent-failure trap across element-data / variables /
actions, with a pre-upload lint (lint-plugin.mjs) that flags it.
The three build-failure stages (local vite dev / upload-time transform / runtime
esm.sh resolution) and the Dev-URL-mode workbook verification + autonomous loop.
The empty-manifest.url registerPlugin crash (the host-side fix is slate #71979).

Reviewer focus

lint-plugin.mjs ships alongside the skill; the in-skill invocation path is
repo-relative (node .claude/skills/sigma-plugin/lint-plugin.mjs <dir>).
Commands reference the sigcli surface where upload-source/pull-source live
today; the binary rename to sigma and porting those two verbs into the new
sigma-cli are tracked separately.

Testing

N/A — documentation/skill only.

Pearce-Ropion · 2026-07-23T17:27:30Z

+1. **sigcli installed and authenticated.** Run `sigcli auth status` — it must report `Auth: OK` against the target Sigma instance. Configure with env vars (`SIGMA_BASE_URL`, `SIGMA_CLIENT_ID`, `SIGMA_CLIENT_SECRET`) or `sigcli auth login`. The **`plugins_v2`** feature flag must be enabled for `/v2/plugins` (create/list/get) and **`plugins_no_bundle`** for `/v2/plugins/:id/source` (upload/pull). If `sigcli` is missing or auth fails, stop and ask the user to install/configure it.
+2. **`context7` MCP available (strongly recommended).** Used to look up the current `@sigmacomputing/plugin` API surface. If not connected, warn the user that you'll fall back to reading the published `.d.ts`, and you may refuse to ship code for any API call you can't confirm.
+3. **A browser-driving MCP for runtime verification (recommended; required to verify the running plugin).** Building and deploying need no browser. But to *verify the plugin actually renders and shows correct data* — the runtime feedback stage — you drive the workbook in a browser. **`playwright` MCP is the one to use: it is the only channel that captures the plugin's cross-origin iframe `console`** (errors, and the `validateConfigId` / element-data warnings). `chrome-devtools` MCP works for screenshots and DOM snapshots but its `list_console_messages` sees only the main frame, **not** the plugin iframe — so it cannot carry runtime error feedback on its own. If neither is connected, you can still build and deploy, but tell the user you cannot verify runtime behavior and fall back to the DOM-instrumentation pattern (render state + captured `console` into a `data-testid` block) read via screenshot. See "Verifying the Deploy" and the autonomous dev loop below.
+4. **No build toolchain required to deploy.** `node`/`npm` are optional — only useful if the user wants to type-check locally. Deployment uploads source; Sigma builds it.


Suggested change

4. **No build toolchain required to deploy.** `node`/`npm` are optional — only useful if the user wants to type-check locally. Deployment uploads source; Sigma builds it.

4. **No build toolchain required to deploy.** `node` is optional — only useful if the user wants to type-check locally. Deployment uploads source; Sigma builds it.

Pearce-Ropion · 2026-07-23T17:28:39Z

+
+**Before writing any code that uses the library:**
+1. **Preferred:** call the `context7` MCP for library `@sigmacomputing/plugin` and consult the returned examples.
+2. **Fallback:** read the published types at `node_modules/@sigmacomputing/plugin/dist/index.d.ts` (after an optional `npm install` for local tooling).


Suggested change

2. **Fallback:** read the published types at `node_modules/@sigmacomputing/plugin/dist/index.d.ts` (after an optional `npm install` for local tooling).

2. **Fallback:** read the published types at `node_modules/@sigmacomputing/plugin/dist/index.d.ts` (after an optional install for local tooling).

Pearce-Ropion · 2026-07-23T17:31:18Z

+  - viz empty despite bound columns → hit the 25k cap, or wrong grain (aggregate the source).
+  - a column won't appear in the picker → `allowedTypes` mismatch (see above).
+
+## Actions, variables & interactions


I think we eventually want to sunset variables/interactions in the plugin API in favor of only actions. I think we should exclude both from this documentation.

Correct me if I am wrong @peternandersson

Pearce-Ropion · 2026-07-23T17:32:19Z

+sigcli plugins create --json '{"name":"<plugin-name>","description":"<desc>","type":"element"}'
+```
+
+The response is JSON containing a `pluginId`. **Write `.sigma-plugin.json` immediately** (before anything else) so a retry reuses the same `pluginId` instead of creating a duplicate.


Why doesn't sigcli write this file for you?

Pearce-Ropion · 2026-07-23T17:32:49Z

+**2. Deploy** — upload the source tree:
+
+```sh
+sigcli plugins upload-source --plugin-id <pluginId> --dir .


Why can't sigcli read the cwd and pull the pluginId from the .sigma-plugin file for you?

Pearce-Ropion · 2026-07-23T17:51:46Z

Convert this file to typescript. Node 24 can execute TS natively.

Pearce-Ropion · 2026-07-23T17:52:11Z

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+// Sigma plugin author-time lint (plugin-authoring-reliability plan, P0-2).


What is the P0-P2 thing here?

Pearce-Ropion · 2026-07-23T17:52:26Z

+#!/usr/bin/env node
+// Sigma plugin author-time lint (plugin-authoring-reliability plan, P0-2).
+//
+// Catches the #1 silent-failure trap BEFORE upload: passing a config *key*


Convert this comment to a file level jsdoc

Pearce-Ropion · 2026-07-23T17:53:22Z

+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join, extname } from 'node:path';
+
+const dir = process.argv[2] || '.';


Suggested change

const dir = process.argv[2] || '.';

const dir = process.argv[2] || process.cwd();

Pearce-Ropion · 2026-07-23T17:57:42Z

I would recommend that we build and publish a custom eslint/oxlint plugin that properly parses the AST tree. regex string matching is notoriously slow and prone to false positives or just plain missing things.

guyathomas requested a review from a team July 23, 2026 16:37

docs(skill): add no-bundle sigma-plugin skill (upload-source) + lint

afa4bdf

guyathomas force-pushed the guy/plugins-v2 branch from 005a55d to afa4bdf Compare July 23, 2026 16:49

guyathomas changed the title ~~docs(skill): reconcile sigma-plugin skill to the sigma CLI plugins surface~~ docs(skill): add no-bundle sigma-plugin skill (upload-source) + lint Jul 23, 2026

Pearce-Ropion reviewed Jul 23, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(skill): add no-bundle sigma-plugin skill (upload-source) + lint - #69

docs(skill): add no-bundle sigma-plugin skill (upload-source) + lint#69
guyathomas wants to merge 1 commit into
mainfrom
guy/plugins-v2

guyathomas commented Jul 23, 2026 •

edited

Loading

Uh oh!

Pearce-Ropion Jul 23, 2026

Uh oh!

Pearce-Ropion Jul 23, 2026

Uh oh!

Pearce-Ropion Jul 23, 2026

Uh oh!

Pearce-Ropion Jul 23, 2026

Uh oh!

Pearce-Ropion Jul 23, 2026

Uh oh!

Pearce-Ropion Jul 23, 2026

Uh oh!

Pearce-Ropion Jul 23, 2026

Uh oh!

Pearce-Ropion Jul 23, 2026

Uh oh!

Pearce-Ropion Jul 23, 2026

Uh oh!

Pearce-Ropion Jul 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	4. No build toolchain required to deploy. `node`/`npm` are optional — only useful if the user wants to type-check locally. Deployment uploads source; Sigma builds it.
	4. No build toolchain required to deploy. `node` is optional — only useful if the user wants to type-check locally. Deployment uploads source; Sigma builds it.

	2. Fallback: read the published types at `node_modules/@sigmacomputing/plugin/dist/index.d.ts` (after an optional `npm install` for local tooling).
	2. Fallback: read the published types at `node_modules/@sigmacomputing/plugin/dist/index.d.ts` (after an optional install for local tooling).

		@@ -0,0 +1,87 @@
		#!/usr/bin/env node
		// Sigma plugin author-time lint (plugin-authoring-reliability plan, P0-2).

	const dir = process.argv[2] \|\| '.';
	const dir = process.argv[2] \|\| process.cwd();

Uh oh!

Conversation

guyathomas commented Jul 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Purpose

What the skill covers

Reviewer focus

Testing

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

guyathomas commented Jul 23, 2026 •

edited

Loading